Tool to join (build), split, and validate OpenAPI 3.0 YAML API specification files using a standardised directory and file naming convention.
Also includes several commands to generate familiar ReadMe.io-compatible documentation snippets to help preserve structure and style.
Install as a the CLI command evrythng-openapi-tools
:
$ npm i -g evrythng-openapi-tools
Join repository spec files that meet the standardised directory and file naming
convention by providing paths to base.yaml
files.
More than one input directory (i.e: multiple API projects) can be specified after the output directory. Each must meet the directory structure outlined below.
$ evrythng-openapi-tools join $inputDir $outputDir [$inputDir2, ...]
Split a single OpenAPI spec file into components that meet the standardised directory and file naming convention by providing the full spec and desired output directory.
$ evrythng-openapi-tools split $specFile $outputDir
Validate an existing or joined OpenAPI spec file.
$ evrythng-openapi-tools validate $specFile
Lint all in schemas
and paths
for common things like example
, and
description
to help ensure format consistency.
$ evrythng-openapi-tools lint $specFile
To generate a page designed for ReadMe.io for a given API, use the print page
command specifying the tag
for the API. The output will be written to a
local file of the same name as the tag
. specFile
is the complete spec file
obtained using the join
command:
$ evrythng-openapi-tools print $specFile page $tag
Some sections and examples will still need to be finished manually.
If more granular printing of individual page sections is needed, use the following commands:
- Print API Status
- Print Definitions
- Print Operations
- Print Filter Table
- Print API Key Permissions List
Print the 'API Status' section for a given tag
, such as Thngs
. Paths with
operations using the tag will be listed as 'General Availability' unless the
path has x-api-status
set to something else, such as 'Beta'. For example:
/thngs/{thngId}:
x-api-status: Beta
get:
tags:
- Thngs
summary: Read a Thng
...
$ evrythng-openapi-tools print $specFile api-status $tag
Run definition
, but for all definitions associated to a tag
, such as
"Thngs". You will be asked to order the applicable definitions before the final
output is printed.
$ evrythng-openapi-tools print $specFile definitions $tag
Included in
definitions
.
Print a trio of 'Fields', 'Schema', and 'Example' for documentation purposes.
The summaryName
should be a summary
from an operation that uses the schema
in its responses
.
If the definition contains any $ref
to other schemas, A 'See Also' section
will also be generated as expected at the bottom of the widget.
If the definition includes x-filterable-fields
, a table of filterable fields
and supported operators will be included as well.
$ evrythng-openapi-tools print $specFile definition $schemaName $summaryName
Included in
definition
.
Print the properties of a schema as a list of fields + attributes for documentation purposes.
$ evrythng-openapi-tools print $specFile fields $schemaName
Included in
definition
.
Print a reduced JSON Schema of a schema component for documentation purposes.
$ evrythng-openapi-tools print $specFile schema $schemaName
Print Request/Response widget pairs for a given tag
all at the same time. You
will be asked to order the applicable summaries before the final output is
printed.
$ evrythng-openapi-tools print $specFile operations $tag
Included in
operations
.
Print a ReadMe.io-compatible Request/Response widget pair, featuring muliple language examples, by summary such as 'Read all Thngs'.
$ evrythng-openapi-tools print $specFile operation $summary
Print a ReadMe.io-compatible table widget for use in the Filters documentation page as the list of 'Available Fields' for all resource types.
$ evrythng-openapi-tools print filter-table
Print the list of endpoints and which keys can access them as shown in the API Keys and Permissions page.
$ evrythng-openapi-tools print $specFile keyPermissions
The directory structure for each repository's spec mirrors the internal structure of a single OpenAPI spec:
/paths
/components
/schemas
/requestBodies
/parameters
base.yaml
The following file naming conventions allow easy splitting and joining of component files, as well as processing by documentation and testing tools.
Contains openapi
, info
, etc. Example:
base.yaml
Must contain 'components' with empty objects for each of 'schemas', 'requestBodies', and 'parameters'.
A file containing an OpenAPI path
object, where the key has /
replaced with
-
. Example:
projects-{projectId}-applications-{applicationId}.yaml
A file containing a single OpenAPI parameters
object, which is the parameter
name
. Example:
projectId.yaml
A file containing a single requestBody
object, which is the request body
name
. Example:
ProjectDocumentCreateBody.yaml
A file containing a single schemas
object, which is the schema name. Example:
ThngDocument.yaml