How does it do it?

You define a set of Documentation Elements that are added to the original swagger.json.

A Documentation Element is effectively a Json token that corresponds to a missing piece of the documentation. This could be to change a default value, to add a new property and value, to add a whole new definition structure or to remove an element. They are added to the baseline swagger.json to give you an updated, more accurate API specification.

Why?

As an example, consider the case where the Outsystems swagger.json only includes the 200 response code for an API endpoint. If your endpoint actually responds with other status codes the documentation won’t reflect this.

Ordinarily you would need to manually edit the swagger.json file to make these type of alterations. If the baseline swagger.json file changes you would then have to merge the altered swagger.json with the new baseline.

With API Doco, the baseline can change at any point as the Documentation Elements are simply added over the top.

Features

• Can be used with any swagger.json, not just Outsystems
• Add any type of Documentation Element
• Json viewer to easily navigate and visualise
• SwaggerUI and ReDoc html templates
• Versioned swagger.json, swaggerui.html and redoc.html files
• Export and Import

Benefits

• Easily add any missing content
• Generate an accurate OpenAPI specification
• Quickly visualise the final result

Demo

Log on using user/user123 to view the API Doco for API Doco (i.e. itself).

Acknowledgments

JsonPrettyFormat – Used as the basis for the Json Viewer