Expert Python Programming - Third Edition

Self-documenting APIs with Swagger/OpenAPI

While self-documenting APIs is a more traditional approach for documenting web APIs (compared to documenting through API prototypes), we can clearly see some interesting trends that appeared during the past few years. In the past, when API frameworks had to support auto-documentation capabilities, it almost always meant that the framework had a built-in API metadata structure with a custom documentation rendering engine. If someone wanted to have multiple services auto-documented, they had to use the same framework for every service, or decide to have very a inconsistent documentation landscape.

With the advent of microservice architectures, this approach becomes extremely inconvenient and inefficient. ...