apidays Paris 2024 - An Alternative View on OpenAPI Docs, Start Finally Doing it Right!, Maxim Danilov

An Alternative View on OpenAPI Docs, Start Finally Doing it Right!
Maxim Danilov, Software Architect, Senior Developer

apidays Paris 2024 - The Future API Stack for Mass Innovation
December 3 - 5, 2024

------

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 documentation. An alternative view. Maxim Danilov maxim@wpshop.at
2. Who I am: • Maxim Danilov, more than 26 years in development • 9 years Python / Django • Over 6 years of working with various JS frameworks • Award-winning mentor in engineering 12/22/2024 Maxim Danilov, maxim@wpshop.at 2 Link to repository: bitbucket.org/danilovmy/conferences2024/src/master/apidays/
3. Thanks to my family for the support: To my animals: Marselle and Kisa 12/22/2024 Maxim Danilov, maxim@wpshop.at 3 To my wife:
4. Special thanks for the illustrations to my children: Maja & Mark 12/22/2024 Maxim Danilov, maxim@wpshop.at 4
5. Part 1 Problem 12/22/2024 Maxim Danilov, maxim@wpshop.at 5
6. OpenAPI Specification: OAS defines how to describe interface of HTTP APIs 12/22/2024 Maxim Danilov, maxim@wpshop.at 6
7. Why we need it? • 1. Documentation of the expected behaviour of API‘s (contract) • 2. Source for autogenerated code (client/server/models) • 3. Used in TDD • 4. Used in tests • 5. Allows to develop independently and Front and back • .… 12/22/2024 Maxim Danilov, maxim@wpshop.at 7
8. Alternatives: Descriptions of REST APIs API-Blueprint (md), RAML (yaml), etc... Descriptions of other APIs GraphiQL etc… 12/22/2024 Maxim Danilov, maxim@wpshop.at 8
9. OpenAPI motto: Properly defined OpenAPI documentation allows both humans and computers to discover, how to interact with the remote service. https://spec.openapis.org/oas/v3.1.1.html#abstract 12/22/2024 Maxim Danilov, maxim@wpshop.at 9
10. How to discover? Django-RestFramework: https//my.domain.it/api/schema/schema.yml https://github.com/tfranzel/drf-spectacular/ Spring: https//my.domain.it/context-path/v3/api-docs (json) https://springdoc.org/#getting-started Fastapi: https//my.domain.it/openapi.json https://fastapi.tiangolo.com/how-to/conditional-openapi/ 12/22/2024 Maxim Danilov, maxim@wpshop.at 10
11. First Problem: OpenAPI spec does not offer definitions on how my OpenAPI documentation can be organized for easy discovery. 12/22/2024 Maxim Danilov, maxim@wpshop.at 11
12. First Problem: Open API does not offer definitions on how the OpenAPI specification can be organized for easy discovery. 12/22/2024 Maxim Danilov, maxim@wpshop.at 12
13. OpenAPI motto: Properly defined OpenAPI spec allows both humans and computers to discover, how to interact with the remote service. https://spec.openapis.org/oas/v3.1.1.html#abstract 12/22/2024 Maxim Danilov, maxim@wpshop.at 13
14. „human readable“ OpenAPI yaml 12/22/2024 Maxim Danilov, maxim@wpshop.at 14
15. Visualization. 12/22/2024 Maxim Danilov, maxim@wpshop.at 15
16. mixed up concepts Human-readable ≠ Human-understandable 12/22/2024 Maxim Danilov, maxim@wpshop.at 16
17. What is about computers? • Azure OpenAPI specification import parsing errors • YAML parsing error on perfectly valid file (symfony) • yaml parse error helm – kubernetes • etc.. 12/22/2024 Maxim Danilov, maxim@wpshop.at 17
18. Second Problem: In a big OpenAPI specification, it's really hard for both humans and computers to discover anything, especially bugs 12/22/2024 Maxim Danilov, maxim@wpshop.at 18
19. Testing: 1. Create internal.yaml for project 2. Create endpoints with YAML Code Generator from internal.yaml 3. Create external services with YAML Code Generator from external.yaml and mocked data. 4. Test endpoints with integrational tests. 12/22/2024 Maxim Danilov, maxim@wpshop.at 19
20. Problem: Testing with a big OpenAPI specification consumes too many CI/CD minutes per month. And therefore very expensive. 12/22/2024 Maxim Danilov, maxim@wpshop.at 20
21. Real project: 12/22/2024 Maxim Danilov, maxim@wpshop.at 21 µdj µdj µdj µdj µdj django
22. Real project: 12/22/2024 Maxim Danilov, maxim@wpshop.at 22 µdj µdj µdj µdj µdj django
23. Real project: 12/22/2024 Maxim Danilov, maxim@wpshop.at 23 µdj µdj µdj µdj µdj django
24. Real project: 12/22/2024 Maxim Danilov, maxim@wpshop.at 24 µdj µdj µdj µdj µdj django
25. Real project: 12/22/2024 Maxim Danilov, maxim@wpshop.at 25 µdj µdj µdj µdj µdj django
26. Real project: 12/22/2024 Maxim Danilov, maxim@wpshop.at 26 µdj µdj µdj µdj µdj django
27. Real project: 12/22/2024 Maxim Danilov, maxim@wpshop.at 27 µdj µdj µdj µdj µdj django
28. TLDR: 12/22/2024 Maxim Danilov, maxim@wpshop.at 28 YAML
29. Other OpenAPI problem: • It is a formal standard for describing HTTP APIs. • Different standards 2.0, 3.0, 3.1, Arazzo v1.0.0 (29.05.2024) • The automatically generated OpenAPI-yaml was never fully correct according to the chosen Standard. • …. 12/22/2024 Maxim Danilov, maxim@wpshop.at 29
30. Part 2 Solution 12/22/2024 Maxim Danilov, maxim@wpshop.at 30
31. Solution „Divide-and-conquer”: Dividing the OpenAPI specification into the smallest possible fragments. 12/22/2024 Maxim Danilov, maxim@wpshop.at 31
32. Method Handler PATCH PATCH Smallest fragments - single entrypoint (route): 12/22/2024 Maxim Danilov, maxim@wpshop.at 32 POST OPTIONS
33. method: OPTIONS 12/22/2024 Maxim Danilov, maxim@wpshop.at 33 • The HTTP OPTIONS method provide options for a given URL. • Request without body • Response may has body • Safe • Idempotent • No Cacheable • Not Allowed in HTML forms
34. Method Handler / router PATCH PATCH OPTIONS as YAML provider for single entrypoint 12/22/2024 Maxim Danilov, maxim@wpshop.at 34 POST OPTIONS / yaml
35. Single endpoint Second step, single service: 12/22/2024 Maxim Danilov, maxim@wpshop.at 35 Yaml composer Single endpoint Single endpoint Route collections urlpaths, Router, BaseRouter, DefaultRouter, etc. Single endpoint Yaml source Yaml source Swagger ui
36. Whatever cloud services Whatever cloud services Self hosted services Self hosted services Global infrastructure: 12/22/2024 Maxim Danilov, maxim@wpshop.at 36 url Routing table (nginx, route 53) Whatever cloud service Self hosted service Yaml-composer/ SwaggerUI Yaml / Swagger ui Yaml / Swagger ui Yaml composer Swagger ui
37. Single project level, different services Single service level, different entrypoints Single endpoint level, different methods Global overview of Yaml generation pipeline: 12/22/2024 Maxim Danilov, maxim@wpshop.at 37 Routing table Yaml gen SwUI Yaml gen Service router SwUI Rote to Yaml Rote to Yaml OPTIONS handler POST handler method dispatcher Dispatch to OPTIONS Docstring
38. Advantages of docstrings in the usual form: 1. Usable for Sphinx (sphinx.ext.autodoc, sphinx-autoapi) 2. Support from Linters (pydoclint, JavaDocLint, …) 3. Docstings collapsable in IDE 4. … 12/22/2024 Maxim Danilov, maxim@wpshop.at 38
39. Real implementation on python 12/22/2024 Maxim Danilov, maxim@wpshop.at 39
40. Part 3 Benefits 12/22/2024 Maxim Danilov, maxim@wpshop.at 40
41. Advantages of using OPTIONS as yaml-source: 1. Clear Yaml location. Send request.OPTIONS to the route. 12/22/2024 Maxim Danilov, maxim@wpshop.at 41
42. Advantages of using OPTIONS as yaml-source: 1. Clear Yaml location. Send request.OPTIONS to the route. 2. Easy to use in tests, to get yaml - ask the test route. 12/22/2024 Maxim Danilov, maxim@wpshop.at 42
43. Advantages of using OPTIONS as yaml-source: 1. Clear Yaml location. Send request.OPTIONS to the route. 2. Easy to use in tests, to get yaml - ask the test route. 3. Faster for CI/CD pipelines. You only get what you need! 12/22/2024 Maxim Danilov, maxim@wpshop.at 43
44. Advantages of using OPTIONS as yaml-source: 1. Clear Yaml location. Send request.OPTIONS to the route. 2. Easy to use in tests, to get yaml - ask the test route. 3. Faster for CI/CD pipelines. You only get what you need! 4. Smaller yaml is more human readable 12/22/2024 Maxim Danilov, maxim@wpshop.at 44
45. Advantages of using OPTIONS as yaml-source: 1. Clear Yaml location. Send request.OPTIONS to the route. 2. Easy to use in tests, to get yaml - ask the test route. 3. Faster for CI/CD pipelines. You only get what you need! 4. Smaller yaml is more human readable 5. etc..... 12/22/2024 Maxim Danilov, maxim@wpshop.at 45
46. Part 4 Initiative 12/22/2024 Maxim Danilov, maxim@wpshop.at 46
47. My OpenAPI intiative Add a recommendation in the Openapi Spec next gen to use HTTP method.OPTIONS as the source of OpenAPI documentation for the selected route. 12/22/2024 Maxim Danilov, maxim@wpshop.at 47
48. Summary 12/22/2024 Maxim Danilov, maxim@wpshop.at 48
49. Summary: • OpenAPI documentation is important. • The OpenAPI-yaml generation process is complex. • A splitting yaml file can improve the usability. • OPTIONS method can be used to get documentation. • Docstrings can be used to generate OpenAPI documentation. 12/22/2024 Maxim Danilov, maxim@wpshop.at 49
50. I wish you happy documentation. Maxim Danilov maxim@wpshop.at Slides and code examples on: bitbucket.org/danilovmy/conferences2024/ 22.12.2024 50