Package: openapi-to-asciidoc
OpenAPI Specification to AsciiDocOverviewThe 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.InstallationTo use the templates, you need to install the openapi_to_asciidoc module.pipinstall-Uopenapi-to-asciidocUsageTo convert your OpenAPI Specification, type:$pythonopenapi_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 to provide an PR or file an issue.Objectsopenapi-to-asciidoc 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 inobjects.pyand 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:vardata=get_json_data()# Get json data of the Schema object however you likeschema_as_asciidoc:SchemaObject=SchemaObjectSchema().load(data)# Render the SchemaObjectprint(schema_as_asciidoc.result)# Print the asciidoc generated outputThe code inconvert.pyis a good starting point to examine what's going on under the hood.RequirementsIn order to run the templates, you need to have following installed:PythonpipPIP DependenciesJinja2marshmallowKnown bugs and issuesNested 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.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.Special characters.Sometimes JSON specifications contains characters that are used for styles in AsciiDoc (like quotes '', asterisk *, HTML tagsetc.). 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.Specification extensionsThere 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.LimitationsThe API Specification needs to be in JSON format, and built according to theOpenAPI 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.Possible improvementsEscaping of special charactersSome characters like i.e html tags could possibly be handled better.Schema objectis 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.ContributeWant to help out? Readthis.