Swagger API Documentation



Swagger is one of the leading standards in API documentation, it's been around ever since 2011 and is the product of SmartBear, the company that made a similar tool in SOAPUI. The community is pretty active and it currently support a wide range of languages: Clojure, Go, JS, Java, .Net, Node, PHP, Python, Ruby, Scala, for each of these languages many frameworks are supported. Swagger ultimately provides a JSON file which can be interpreted by the Swagger UI or any other Custom Tool that supports it. If the framework in use is not supported by Swagger it's easy to build this JSON file as part of a custom strategy in the project, and any of the custom UI tools should work, provided the JSON file complies with the Swagger standard.

Integration

Because Swagger is basically a JSON file following the standard, documenting Swagger can be achieved via different ways such us, Static Files, Manually crafted JSON, Code inspection, Code comments, static annotations or Runtime generation.

There are many tools that follow the annotation path, usually in a manner similar to javadoc or .NET documentation, then use a parsing and codegen module tailored to the service's programming language or framework, along with Swagger UI, to generate the interactive interface to the REST APIs. Swagger annotations are kept inline with the source, colloquially speaking is good to just have it 'there', while making changes to resources, one can easily update the documentation without forgetting. It also means that in order to update Documentation, one has to modify source files, this may delay the documentation update depending on the team deployment/testing strategy.

If the documentation gets generated at runtime, no external tool needs to run on the CI process. This is best practice to keep documentation in sync with the API.

Tags