The OpenAPI Specification to AsciiDoc is a set of Jinja2 templates that will help you create readable API documentation from a JSON OpenAPI Specification file.
AsciiDoc is a versatile plain-text writing format which you can use as it is, or can easily be converted to pdf.
To use the templates, you need to install the openapi_to_asciidoc module.
pip install -U openapi-to-asciidocTo convert your OpenAPI Specification, type:
$ python openapi_to_asciidoc -j <path-to-open-api-spec>.json -o <path-to-output-file>.adocThis will generate an AsciiDoc from your OpenAPI Specification.
The templates are created with the OpenAPI Specification v.3.1.0 as a base. If your specification contains sections that are not included or requires improvement, please feel free to contribute.
This module creates objects with the help of Marshmallow in order to generate the templates. Each Object of the specification follows the rules of its SchemaObject and can be generated independently, but most users will probably use the OpenAPISchema as their starting point.
All Objects of the OpenAPI specification are represented in models.py and can be changed and modified depending on your needs. All but the OpenAPI object has their call to super() commented out to speed up processing. If you would like to just render a specific model, just enable the call to super() and you are good to go!
Example: if you where to render and print just the Schema Object from an json string containing SchemaObject data, You would make the call to Super in the SchemaObject's init method, then you could just render it like this:
var data = get_json_data() # Get json data of the Schema object however you like
schema_as_asciidoc: SchemaObject = SchemaObjectSchema().load(data) # Render the SchemaObject
print(schema_as_asciidoc.result) # Print the asciidoc generated outputThe code in convert.py is a good starting point to examine what's going on under the hood.
In order to run the templates, you need to have following installed:
- Python
- pip
The module uses Jinja2 template engine and Marshmallow which are both installed automatically.
1 Nested objects and lists. Objects using it's own Schema to render fields (Like the SchemaObjectSchema) might get less than perfect output if it contains a lot of nested objects.
2 Page breaks. The generated document is just an AsciiDoc, so if you want to export it as a PDF for example, there is no functionality for page breaks.
3 Special characters. Sometimes JSON specifications contains characters that are used for styles in AsciiDoc (like quotes '', asterisk *, HTML tags etc.). There is no handling of these characters, so some sections may look a bit odd. These issues often appear when an object or list is too nested for the template.
4 Specification extensions There might be some inconsistencies in how the specification support is presented in the finished AsciiDoc document. If this is a feature that is widely used, the implementation may have to be tweaked to each individual template.
The API Specification needs to be in JSON format, and built according to the OpenAPI Specification standard. If your specification contains sections that are not stated in the OpenAPI Specification, the template will not print that information in the generated document.
-
Escaping of special characters Some characters like i.e html tags could possibly be handled better.
-
Schema object is referring to it self during parsing, which works fine for most use cases, but if you have Schema objects with nested properties for example, the output will look a bit strange. This could be handled differently, but given the Schema object's flexible structure, there might be a need to tweak this object to best suit your needs anyways.
Want to help out? Read this.
v 0.1 - initial release.
Licensed under MIT