oas2md is a simple program to create markdown documentation of an OpenAPI defined API. It uses libopenapi to parse the specification and go templates for rendering the pages.
The program was designed to create pages for a Hugo website but it can also create pages more suitable for display on Github by passing the -g option.
This project is intended for developers who want to create static documentation from their OpenAPI specifications.
Before using oas2md, ensure you have:
- An OpenAPI specification. This can be a file or a URL to a spec.
- golang 1.18+ if developing
When using the binary the templates are embedded.
Get started with oas2md by installing the program.
- Download the latest binary from Github
Oas2md will create markdown files from your OpenAPI specification. All configuration is done via command-line switches. By default it will create Hugo-compatible files with the main file being _index.md.
Command-line switches:
-d
: The directory in which to create the file(s)
-s
: The location of the specification. Can be a filepath or URL
-g
: makes Github-compatible files. The main page is README.md
-1
: creates a single file for the entire API rather than a file per path
The program will panic if there are any issues creating files, rendering templates, etc. Most errors can be traced back to issues with the specification. The program attempts to validate the spec before running, but some issues can still get through. It is recommended to run the spec through Vacuum and clean up any issues before attempting to generate the documentation.
If you wish to contribute to oas2md fork the project and submit a pull request.
Requests for help can be made by starting a discussion on Github. Problems can be reported by creating an issue.
oas2md is licensed under the MIT License.