Presidium OpenAPI 3

A Golang tool for importing your OpenAPI 3 spec into
Presidium documentation.

Generation

This tool can be run as a:

- Standalone executable:
- Part of your Presidium Project

Install

Install presidium-oapi3 globally

With Brew - Recommended for ARM64
``shell
brew tap SPANDigital/homebrew-tap https://github.com/SPANDigital/homebrew-tap.git
brew install presidium-oapi3

`

With NPM
`shell
npm install -g presidium-oapi-3
`

Run

Execute presidium-oapi3 will print the usage:

`shell
presidium-oapi3 -h
`

`text
A Presidium tool that converts OAPI3 spec's to markdown

Usage:
presidium-oapi3 [flags]
presidium-oapi3 [command]

Available Commands:
convert Converts an OpenAPI 3 spec to markdown
help Help about any command

Flags:
-h, --help help for presidium-oapi3

Use "presidium-oapi3 [command] --help" for more information about a command.
`

To convert a file you can use the convert command:

`text
Usage:
presidium-oapi3 convert [flags]

Flags:
-e, --allowExternalRefs Allow external references in the OpenAPI spec.
-n, --apiName string The name under which the generated docs will be grouped
-f, --file string OpenAPI 3 spec file
--includeExamples Include a column on the schema for examples
--includeRestrictions Include a column on the schema for restrictions (default true)
-i, --inlineProperties Inline properties in the request and response schemas
-o, --outputDir string The output directory
-r, --referenceURL string The reference URL (default "reference")
-s, --sortFilePath Sort by filepath by prefixing a weight to the filename. Default is to use front matter weight
-t, --titleFormat string The template format used to create the title for each operation.
Valid options are:
- operationId: (Default) Uses the value of the operationId field.
- MethodURL: Uses a combination of the Method property and the URL.
`

Sample usage:
`shell
presidium-oapi3 convert -f api-spec.yaml -o /project/root/path
`

The converter will store the Markdown under the /reference directory by default, but you can change it by using the -r, --referenceURL flag.
`shell
presidium-oapi3 convert -f example.yaml -o /project/root/path -r /custom/path
`

Part Of Your Project

Include as part of the npm build building your Presidium site as in the following sample:

`json
"scripts" : {
"import-open-api-3" : "presidium-oapi3 convert -f -o -r "
},
"devDependencies": {
"presidium-oapi-3" : "#.#.#"
}
``