Restful API接口自动生成markdown/html文档

此处介绍一个方法，用于将Restful API接口自动化生成markdown/html文档，需要用到两个工具

• 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