Apidays Paris 2023 - OpenAPI Extensibility - The Good, The Bad and The Ugly, Oleg Nenashev, WireMock

Apidays Paris 2023 - Software and APIs for Smart, Sustainable and Sovereign Societies
December 6, 7 & 8, 2023

OpenAPI Extensibility - The Good, The Bad and The Ugly
Oleg Nenashev, Community Builder and DevRel Consultant at WireMock

------

Check out our conferences at https://www.apidays.global/

Do you want to sponsor or talk at one of our conferences?
https://apidays.typeform.com/to/ILJeAaV8

Learn more on APIscene, the global media made by the community for the community:
https://www.apiscene.io

Explore the API ecosystem with the API Landscape:
https://apilandscape.apiscene.io/

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)