README
typedoc-plugin-openapi-doc
A typedoc plugin for ingesting jsdoc @swagger or @openapi comments as documentation.
Installation and use
Install via npm; requires a peer of TypeDoc 0.20.20 or above.
npm install --save-dev typedoc typedoc-plugin-openapi-doc
This plugin automatically detects the typedoc plugin for markdown and will skip generating CSS styles for collapsible content.
TypeDoc options
The following options may be defined in a typedoc config. However, all of the options default to true and it is not required that they are provided.
"openapi-doc": {
"hoistDescription": true,
"yaml2Html": false,
"renameTag": "MyNewTagName"
}
Why
The rendering of @swagger
JSDoc tags was ugly to the point of being useless in TypeDoc, which meant ignoring these tags. Additionally, such a comment tag often included additional information that would have to be repeated when writing description documentation for TypeDoc to consume.
The result is this plugin, to reduce copypasta of descriptive information and to render OpenAPI metadata in a more human-readable way.
Other tools which ingest @swagger/@openapi comments
- Project to OpenAPI uses
@swagger
comments. - Swagger JSDoc uses
@swagger
for its notation. - OpenAPI JSDoc uses
@openapi
.
Code documentation
Found here.