Swagger and OpenAPI revolutionized the API landscape and created a thriving ecosystem of developer tools, from IDEs to contract testing and no-code solutions. In our projects (WireMock, Jenkins, Testcontainers and WireMock Cloud) we adopted OpenAPI to provide a great developer, and achieved great results. At the same time, the v3 version of specification has too many limitations, especially when it comes to behavior modeling: limited extensions framework, poor response flexibility limiting complex API options, and weak examples and self documentation capabilities. Good news is that OpenAPI v4 (Project Moonwalk) addresses many of those concerns and, hopefully, could address others before the release. Let’s, wearing our end user hats, discuss the v3 experiences and how we could address them in the upcoming major release!

Last slides version: https://speakerdeck.com/onenashev/openapi-extensibility-the-good-the-bad-and-the-yamly

References:

- https://swagger.io/docs/specification/openapi-extensions/
- https://www.jenkins.io/doc/book/using/remote-access-api/
- https://www.jenkins.io/projects/gsoc/2024/project-ideas/automatic-specification-generator-for-jenkins-rest-api/
- https://docs.wiremock.io/openapi/
- https://www.wiremock.io/post/creating-mock-api-templates-from-openapi
- https://github.com/OAI/moonwalk