OpenAPI extensibility - the Good, the Bad and the YAMLy

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!

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

Transcript

1. OpenAPI Extensibility Oleg Nenashev, OpenAPI Initiative / Jenkins / WireMock The Good, The Bad, The YAMLy
2. 2 * Testcontainers/AtomicJar is a WireMock partner
3. OpenAPI Extensions 101 3 https://github.com/OAI/OpenAPI-Specification/blob /main/guidelines/v2.0/EXTENSIONS.md
5. OpenAPI Extensions 101 5 https://github.com/OAI/OpenAPI-Specification/blob /main/guidelines/v2.0/EXTENSIONS.md
8. > whoami @oleg_nenashev oleg-nenashev Dr. Nenashev / Mr. Jenkins Developer tools hacker Community builder & DevRel consultant #RussiansAgainstPutin #StandWithUkraine
9. Kudos to Sponsors of this visit 9 https://www.openapis.org/ https://www.wiremock.io/
11. OpenAPI Extensions github.com/OAI/OpenAPI-Specification/blob/main/guidelines/v2.0/EXTENSIONS.md 11 spec.openapis.org/oas/latest.html#specification-extensions
12. Examples… 12
14. 14 Wait, it’s all just Swagger? OpenAPI 3 Extensions
15. So, but what’s ugly? • No official v3 Documentation • V2 specification has not been updated in ages 15
16. Specification is an inspiration • Nobody cares where “x-” fields are supported or not • Almost everything in “x-” fields? Why not • Encrypted data in spec? Why not? • Contribute back? Why? 16 Image source: https://dev.to/meatboy/what-are-mo dern-examples-of-embrace-extend- and-extinguish-21j3
18. 18 jenkins.io
19. Who is Mr. Jenkins? •Automation server/framework •Popular CI/CD tool •Open-source •Big community •More than 1700 plugins •Part of the Continuous Delivery Foundation
21. 21 New demands Shift left Jenkins evolved … but not fast enough for early adopters API
22. Shifting Gears: Making Changes Aug 31, 2018 – Kohsuke Kawaguchi, “Jenkins: Shifting Gears” https://jenkins.io/blog/2018/08/31/shifting-gears/
24. Swaggy Jenkins Unofficial API specification Client applications generated from it 24 github.com/cliffano/swaggy-jenkins
25. Swagger OpenAPI specs in Jenkins May plugins implement Swagger/Open API specs Recommendation, but not a standard Too difficult to maintain 25 https://www.jenkins.io/blog/2019/08 /16/folder-auth-plugin/#rest-apis-wit h-swagger-support
26. 2,000+ components with REST API 26
27. We wanted to use OpenAPI at Scale • Jenkins has in-house web framework (Stapler + Jetty) • Integrations would benefit from a specification and code generator • We could merge all specifications live for each service instance 27
28. OpenAPI in Google Summer of Code 28 jenkins.io/sigs/gsoc
29. What did I try to put in “x-”? • Authorization model • Feature flags • Conditions • Stateful behavior • … 29 Image source: orchid-tech.com/design-notes/ fpga-complex-algorithm-development/
30. 30 Source: https://medium.com/10-minutes-qa-story/api-testing-from-scratch-api-anatomy-f220856ce9b3
32. Open API as Code • JSON/YAML extensions are not great • OpenAPI specifications are huge and not sustainable as is • It is an interexchange format • 99% of specifications are generated by tools • OpenAPI DSLs 32
35. 35 WireMock 101 WireMock is a tool for building mock APIs 5M+ downloads a month Available beyond Java, inc Rust or Golang You can can: • Create stable development environments • Isolate yourself from flakey 3rd parties • Simulate APIs that don't exist yet wiremock.org
36. 36 wiremock.org/docs/stubbing IF (request_url) THEN (response) * * it gets MUCH more complex WireMock Config JSON: Client library response request Client App Mock API Server HTTP/2
37. WireMock in Java 37 wiremock.org/docs/stubbing
38. WireMock Features 38 wiremock.org/docs
39. WireMock Ecosystem & Features 39 wiremock.org/docs
41. WireMock Cloud by WireMock Inc. 41 • WireMock creator is a co-founder of the Inc. • WireMock Cloud - SaaS for end-to-end API mocking • Private beta: K8s Edition for managed / on-premises • OpenAPI co-development wiremock.io
42. WAS 42 wiremock.io/post/creating-mock-api-templates-from-openapi
43. NEW: API Co-Development 43 wiremock.io/post/ship-api-dependent-features-more-efficiently-with-mock-first-api-prototyping NOTE: Vendor neutral talk, no demo
44. OpenAPI in WireMock Cloud • Full import of OpenAPI => mock API • Bidirectional, incremental OpenAPI <=> mock API generation • Request and response validation • Generation of both specific and loose matching stubs 44 NOTE: Vendor neutral talk, no demo
45. OpenAPI Spec Extensions in WireMock Cloud • x-faker - specify the random value generator for a schema element • x-parameter-values - to specify values of the request parameters associated with a specific response example • x-wiremock-hash - tracking of changes for synchronization 45 NOTE: Vendor neutral talk, no demo
48. 48 github.com/OAI/moonwalk
49. OpenAPI 4 “Moonwalk” • Eliminate complexity • Support APIs that have different responses based on query parameters, headers and request bodies. • Support a broader range of URL design patterns • Reduce nested structures to improve readability and editability • Improve reusability of request and response patterns 49 https://github.com/OAI/moonwalk
50. Moonwalk - My wishlist • ASAP: Get it released! ◦ Later: Other stuff is later • OpenAPI DSL • Adopt popular extensions • Built-in Authorization • Connect Parameters/Responses/Examples • Learn from API Modeling tools 50
51. Learn from API Modeling 51 wiremock.org/docs
53. Takeaways 53 • OpenAPI Extensions are a an engine to consider • Extensions help where the specification does not • OpenAPI 4 Moonwalk will change the things a lot!
54. It’s [always] a great time to contribute! communityinviter.com/apps/open-api/openapi openapis.org/participate/how-to-contribute 54
55. How to participate NOW • Share feedback! • Evolve the spec beyond Swagger • Adopt the spec 55
57. 57 QUESTIONS? 1) API Spec and Standards Booth 2)) WireMock Booth (#12)