Upgrade to Pro — share decks privately, control downloads, hide ads and more …

OpenAPI extensibility - the Good, the Bad and the YAMLy

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!

- 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

Oleg Nenashev

December 06, 2023

More Decks by Oleg Nenashev

Other Decks in Technology


  1. > whoami @oleg_nenashev oleg-nenashev Dr. Nenashev / Mr. Jenkins Developer

    tools hacker Community builder & DevRel consultant #RussiansAgainstPutin #StandWithUkraine
  2. So, but what’s ugly? • No official v3 Documentation •

    V2 specification has not been updated in ages 15
  3. 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
  4. 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
  5. 20

  6. 21 New demands Shift left Jenkins evolved … but not

    fast enough for early adopters API
  7. Shifting Gears: Making Changes Aug 31, 2018 – Kohsuke Kawaguchi,

    “Jenkins: Shifting Gears” https://jenkins.io/blog/2018/08/31/shifting-gears/
  8. 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
  9. 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
  10. 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/
  11. 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
  12. 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
  13. 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
  14. 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
  15. 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
  16. 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
  17. 46

  18. 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
  19. 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
  20. 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!
  21. How to participate NOW • Share feedback! • Evolve the

    spec beyond Swagger • Adopt the spec 55
  22. 56