https://github.com/aaronhuggins/typedoc-plugin-openapi-doc

A typedoc plugin for ingesting jsdoc `@swagger` or `@openapi` comments as documentation.
https://github.com/aaronhuggins/typedoc-plugin-openapi-doc

openapi swagger typedoc typedoc-plugin typedocplugin

Last synced: 9 days ago
JSON representation

A typedoc plugin for ingesting jsdoc `@swagger` or `@openapi` comments as documentation.

• Host: GitHub
• URL: https://github.com/aaronhuggins/typedoc-plugin-openapi-doc
• Owner: aaronhuggins
• License: mit
• Created: 2021-02-05T14:12:31.000Z (almost 4 years ago)
• Default Branch: main
• Last Pushed: 2021-02-09T19:52:00.000Z (almost 4 years ago)
• Last Synced: 2024-05-01T19:31:03.428Z (7 months ago)
• Topics: openapi, swagger, typedoc, typedoc-plugin, typedocplugin
• Language: TypeScript
• Homepage: https://ahuggins-nhs.github.io/typedoc-plugin-openapi-doc/
• Size: 206 KB
• Stars: 1
• Watchers: 1
• Forks: 0
• Open Issues: 2
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

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.

```shell

npm install --save-dev typedoc typedoc-plugin-openapi-doc

```

This plugin automatically detects the typedoc plugin for [markdown](https://github.com/tgreyuk/typedoc-plugin-markdown/tree/master/packages/typedoc-plugin-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.

```json

  "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](https://github.com/ahuggins-nhs/project-to-openapi) uses `@swagger` comments.

- [Swagger JSDoc](https://github.com/Surnet/swagger-jsdoc) uses `@swagger` for its notation.

- [OpenAPI JSDoc](https://github.com/asznee7/openapi-jsdoc) uses `@openapi`.

# Code documentation

Found [here](https://ahuggins-nhs.github.io/typedoc-plugin-openapi-doc/).