Description:

Documenting project endpoints is a real problem in API development. Poor readability, versioning, lack of authentication information all lead to the lack of usability of existing OpenAPI documentation. This talk will present an alternative way to improve the quality of auto-generated OPENAPI documentation.

This talk is based on two years of work with a project that contains about 310 endpoints written in different languages and having different versions of implementations, frameworks, and containing legacy parts. The problem was. that the auto-generated documentation based on static code analysis across different versions of API implementations was completely unusable. Implementation of other open-source solutions for generating OPENAPI documentation and later similar services did not improve the situation. All of this has led to a global rethinking of API documentation creation.

Sadly, we haven't found the "silver bullet". Endpoint documentation still remains poor. But we have found our way to the "plateau of awesome OpenAPI documentation".

What should be reconsidered on this way:

1. Complexity and Learning Curve: Understanding the structure and syntax of OpenAPI specifications (Swagger/ReDoc) can be challenging.

2. Obstacles by Static YAML/JSON Schema Generation - Incomplete or Inaccurate Documentation and due to non-ideal static generators.

3. Maintainability: Keeping accurate and up-to-date OpenAPI documentation in a fast-growing project with frequent updates is not easy.

4. Project API documentation might lack details, omit certain endpoints, parameters, or provide insufficient descriptions. It might not cover edge cases or certain nuances in API behavior, leading to confusion for developers. Also, it reflects some aspects of pure documentation culture in the organization generally.

5. Limited Tooling Support: The ecosystem of OpenAPI tooling for certain specific use cases or languages either does not exist or is only in the nascent stage. This hampers developers relying on different languages or platforms.

6. Readability: OpenAPI documentation is meant for both humans and machines. Balancing between machine-readable format and human-friendly documentation can be challenging. However, easily understandable documentation is crucial for developers.

7. Lack of Standardization and Consistency: In our case, it was a significant problem. Inconsistencies between the actual API implementation and its OpenAPI documentation could mislead developers or model auto-generators and cause compatibility issues.

8. Discoverability: Finding appropriate OpenAPI documentation for a specific API or version, especially in large ecosystems or when working with multiple APIs, can be simply impossible.

9. Versioning Challenges: Managing multiple versions of OpenAPI specifications, especially when APIs have frequent updates or changes, can be problematic. It can be solved through deprecation of versioning, like in Zalando, but deprecation is not always the solution.

10. Security and Authorization Description: Documenting security requirements, authentication methods, and authorization mechanisms is always difficult or not properly confirmed, and it often leads to security vulnerabilities.

11. If the documentation is generated dynamically or if large specifications are parsed and rendered, it can cause problems with reducing performance.

To rethink all these steps, probably we need the whole power of the community for many years. In this talk, I try to show the other perspectives on the perfectly auto-generated API documentation, based on the "divide and conquer" technique together with the use of HTTP/s OPTIONS method.

After this talk, every participant should have tools and important information about properly generated OPENAPI documentations, about appearing problems, and how they can be easily solved.

Prerequisites:

For this talk, minimal knowledge of the auto-documentation tools in python is welcome.

Content URLs:

https://bitbucket.org/danilovmy/conferences2024/src/master/pyconin/docs/OpenAPI.pptx (slides are hidden before start of conference)

Speaker Info:

Senior Python/Django software Engineer, Solution Architect, DevRel and Tech Speaker.

I start my career as a programmer specializing in embedded solutions in 1997, and grow to CTO in 2023. Through many successful projects, I gained a robust understanding of various software development paradigms. In last 10 years as a code mentor, I 've got three times the Award 'Super Mentor in Engineering'

Speaker Links:

Videos from conferences 2024:

• PYCON DE 2024, lightning talk "Let's talk about performance" https://www.youtube.com/watch?v=OsnN9ZjgNOs • PYCON DE 2024, micro Django 2.0, an asynchronous microservices technique. (on English) https://www.youtube.com/watch?v=9BWklCgXahY.

• PYCON SK 2024, workshop Creating of really multilingual Django project. (on English) https://youtube.com/live/Wro9Th_OUhk • PYCON SK 2024, talk, Selecting tools to fight complexity in large Python projects (on English) https://www.youtube.com/watch?v=lSZW0ZMVtk8

• PyCon Lithuania 2024, talk, Django 2.0, an asynchronous microservices technique (on English) https://www.youtube.com/watch?v=Bnw7kxtSCuo. • PyCon Lithuania 2024, talk, Django FTL: Resolving bottlenecks on the path to high performance, (on English) https://www.youtube.com/watch?v=rHhP85L0E2k.

Other talks or projects and blogs by this link: https://gist.github.com/danilovmy/df3bec0fbe0ee264634dad98c8e3c688