OpenAPI: The Good, The Bad, The YAMLy - Gradle Edition

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!

Transcript

1. OpenAPI Extensibility Oleg Nenashev, Baruch Sadogursky, Laura Kassovic The Good, The Bad, The YAMLy
3. Oleg Nenashev - Online Edition @oleg_nenashev oleg-nenashev Dr. Nenashev / Mr. Jenkins Community Builder Developer Tools Hacker DevRel Consultant (#OpenToWork) #RussiansAgainstPutin #StandWithUkraine
4. Online Edition :( 4 Various API calls
5. Baruch Sadogursky - In-Person Edition @jbaruch jbaruch Developer Productivity Advocate DevRel Advisor @Gradle Java Champion CNCF Ambassador Alumni
6. Laura Kassovic - In-Person Edition Technical Writer Community Builder Open Source Advocate Documentation First Approach lkasso
7. Slides&Links: https://speakerdeck.com/onenashev/ Nov 06 Video: https://speaking.jbaru.ch/
8. 8 Developer Productivity Engineering (DPE)
9. Developer Productivity Engineering (DPE) gradle.com/ developer-productivity-engineering
10. 10 x.com/dastbe/status/1303858170155081728
11. 11 The UNIX way Peter H. Salus, A Quarter-Century of Unix (1994) • Write programs that DO ONE THING and DO IT WELL • Write programs to WORK TOGETHER • Write programs to handle text streams, because that is a UNIVERSAL INTERFACE
12. Interoperability and Interfaces are the Key 12
13. Most Apps and Dev Tools Work with APIs 13 response request Client App Server HTTP/2 Storage response request API API
14. API specs API tech
18. 18 OpenAPI 101 Request-Response definitions Parameters Response samples Extensions
19. Huge Tools Ecosystem 19 https://tools.openapis.org
20. Example: OpenAPI plugins for Gradle 100+ related Gradle plugins Libraries and integrations in any [modern] framework (!) OpenAPI Generator 20
21. Who uses OpenAPI? EVERYOOOONE!!!
22. The industry uses OpenAPI, too 22 2021 Data. Source: inform.tmforum.org/features-and-opinion/the-status-of-open-api-adoption
23. We leverage OpenAPI in Develocity, too 23
24. Example: Develocity 24 • Not just OpenAPI, but an API Manual ◦ https://docs.gradle.com/develocity/api-manual • Versioning and Depreciation policy via OpenAPI annotations • User-friendly changelogs
25. Example: OpenAPI Generator 25 https://openapi-generator.tech/ Application Programming Interface • Automates the creation of ◦ client libraries, ◦ server stubs, ◦ API documentation, ◦ and configuration files • from an OpenAPI Spec Input: Output:
26. • ◦ Build Scan and Troubleshooting ◦ Local and Distributed build caching ◦ Predictive Test Selection ◦ CI/CD observability and Insights ◦ Local build observability Public Develocity Instance: ge.openapi-generator.tech We support OpenAPI Generator 26
27. • We support open source • Many projects run with Develocity • Maven, Bazel, sbt.., and Gradle gradle/develocity-oss-projects
28. Huge Tools Ecosystem (RECAP) 28 https://tools.openapis.org
29. Interoperability && Extensibility 29 at scale…
30. 30 OpenAPI 101 Request-Response definitions Parameters Response samples Extensions
31. OpenAPI Extensions github.com/OAI/OpenAPI-Specification/blob/main/guidelines/v2.0/EXTENSIONS.md 31 spec.openapis.org/oas/latest.html#specification-extensions
32. OpenAPI Extensions 101 32 https://github.com/OAI/OpenAPI-Specification/blob /main/guidelines/v2.0/EXTENSIONS.md
33. Example: Develocity API 33 openapi: 3.0.3 info: title: Develocity API description: > Allows programmatic interaction with Develocity, from config to build data version: "2024.2" license: name: Develocity License url: https://gradle.com/legal-gradle-software-license-agreement termsOfService: https://gradle.com/help/legal-terms-of-use x-logo: url: https://assets.gradle.com/logo/develocity-logo.svg altText: Develocity docs.gradle.com/develocity/api-manual/ #reference_documentation
34. Example: Develocity API 34 … tags: - name: BuildCache x-displayName: Build Cache description: | Endpoints related to configuring the Build Cache nodes of the Develocity instance. To access these endpoints the user requires the `Configure build caches` permission. - name: Projects x-displayName: Projects (Beta) description: | Endpoints related to the management of projects in Develocity. To access these endpoints the user requires the `Administer Projects` permission. docs.gradle.com/develocity/api-manual/ #reference_documentation
37. Example: AWS API Gateway 37 https://swagger.io/docs/specification/v3_0/openapi-extensions
38. 38 YAML DevX
39. OpenAPI is not DRY
40. 40 And more constructive!
43. 43 Wait, it’s all just Swagger? OpenAPI 3 Extensions
44. So, but what’s ugly? • Limited v3 Documentation, mostly inherited from Swagger • Little updates and docs before late 2023 • Little “extension specs” 44
45. Specification is an inspiration • Nobody cares where “x-” fields are supported or not • Almost everything in “x-” fields? Why not • Encrypted data in spec? Data blobs? Why not? • Contribute back? Why? 45 Image source: dev.to/meatboy/what-are-modern-examples-of-embrace-extend-and-extinguish-21j3
46. 46 Source: https://medium.com/10-minutes-qa-story/api-testing-from-scratch-api-anatomy-f220856ce9b3
47. Extensions are for lock-in • Most specs are generated by tools, they leverage extensions • JSON/YAML extensions are not great to manage • OpenAPI specifications are huge and not sustainable as is • OpenAPI but with SDKs 47
48. Where did we see “x-”tensions? • Authorization model • Parameter values for samples • Feature flags • Conditions • Stateful behavior • … 48 Image source: orchid-tech.com/design-notes/ fpga-complex-algorithm-development/
51. 51 github.com/OAI/moonwalk OpenAPI 4
52. OpenAPI 4 “Moonwalk” Project Evolve the OpenAPI Specification to: 1. Address limitations in the existing OpenAPI 3.x versions 2. Introduce features that allow for more expressive API definitions, including support for advanced use cases 3. Improve user experience 4. Encourage contributions and community feedback 52 https://github.com/OAI/moonwalk
53. OpenAPI 4 “Moonwalk” Features • Support APIs that have different responses based on query parameters, headers and request bodies. • Broader range of URL design patterns • Reduce nested structures to improve readability and editability • Improve reusability of request and response patterns 53 https://github.com/OAI/moonwalk
54. OpenAPI 4 “Moonwalk” Wishlist: Extensions Registry • OpenAPI 4 should include standard spec extensions • From x-logo to x-auth 54
55. OpenAPI 4 “Moonwalk” Wishlist: Overlay Specifications to become a part of the standard aka “openapi-patch” - injecting duplicated content into the specs spec.openapis.org/ove rlay/v1.0.0.html 55 Source: https://www.youtube.com/watch?app=desktop&v=Iiygq3r1QPs
56. See you at APIDays Paris? Speaking on Developer Experience and Project Moonwalk: • “Walk the OpenAPI Talk, Moonwalk the DevEx!” • Dec 03, 11:00, OpenAPI Track API Specs & Standards Booth 56
57. 57 Source: https://www.businesstoday.in/visualstories/news/will-boeings-starliner-failures-impact-nasas-artemis-3-moon-landing-similar-to-sunita-williams-space-stranding-161968-12-08-2024 PLEASE MAKE IT HAPPEN
58. If you develop OpenAPI Specs 58 • Need more? OpenAPI Extensions are an engine to consider • Extensions help where the specification does not • Try out Moonwalk, share feedback
59. If you consume OpenAPI Specs 59 • Productize API - documentation, tools, versioning and maintenance • Keep your OpenAPI version up to date • Document / Share your extensions
60. Gradle Slack, #developer-productivity OPENQuestions? OpenAPI Initiative Slack 60