Restful APIインタフェースによるmarkdown/htmlドキュメントの自動生成

文書ディレクトリ

Postman

docgen

ここではRestful APIインタフェースを自動化してmarkdown/htmlドキュメントを生成する方法を説明します.2つのツールが必要です.

Postman(Restful APIインタフェース開発試験ツール)

docgen(APIドキュメント生成ツール)

Postman
collectionをダウンロード、インストール、作成し、collectionでRestful APIの開発を行い、開発テストに使用します.ここでは詳しく説明しません.
APIを開発した後、APIをjsonファイルにエクスポートし、postmanツールでcollectionをクリックし、Exportを選択すると実現します.
docgen
ダウンロード先:https://github.com/thedevsaddam/docgen
インストール
ツールの使用方法の説明:

[root@×××]$ docgen --help

 _____                _____
|  __ \              / ____|
| |  | | ___   ___  | |  __  ___ _ __
| |  | |/ _ \ / __| | | |_ |/ _ \ '_ \
| |__| | (_) | (__  | |__| |  __/ | | |
|_____/ \___/ \___|  \_____|\___|_| |_|

Generate API documentation from Postman JSON collection
For more info visit: https://github.com/thedevsaddam/docgen

Usage:
  docgen [command]

Available Commands:
  build       Build html/markdown documentation from postman collection
  help        Help about any command
  server      Serve live html from postman collection
  version     Provide version information

Flags:
  -h, --help   help for docgen

Use "docgen [command] --help" for more information about a command.

ツール使用例postmanからエクスポートされたjsonファイル名をpostmanと仮定collection.json

To view live HTML documentation from postman collection

docgen server -f postman_collection.json -p 8000

This will open the html version of postman collection to the defined port

To view live Markown documentation from postman collection

docgen server -f postman_collection.json -p 8000 -m

To make HTML documentation

docgen build -i postman_collection.json -o ~/Downloads/index.html

To make Markdown documentation

docgen build -i postman_collection.json -o ~/Downloads/index.md -m