MKDOC

灵活可定制,多语言支持的API文档生成器

快速开始

• 使用 (Command)

GO111MODULE=on go get github.com/thewinds/mkdoc/cmd/mkdoc

cd /path/to/your/projet
# 初始化
mkdoc init
# 修改配置
vim conf.yaml
# 代码注解
# ...
# 生成文档
mkdoc make

• 使用 (DocServer)

# 1.pull
docker pull thewinds/mkdoc-server
# 2.set Environments and Config file
# 3.run
# you will see:
# 2020/05/16 18:48:47 server docs:
# 2020/05/16 18:48:47     index   =>      127.0.0.1:8080
# 2020/05/16 18:48:47     project_0 =>      127.0.0.1:8080/project_0
# 2020/05/16 18:48:47     project_1  =>      127.0.0.1:8080/project_1
# 2020/05/16 18:48:47 notify url: 127.0.0.1:8080/notify

web listen port is :8080

notify url is :8080/notify

环境变量

名称	描述
GIT_USER_NAME	user name for private git repository
GIT_PASSWORD	password for private git repository
NOTIFY_TOKEN	token for notify docserver
WEB_USER_NAME	basic auth username
WEB_PASSWORD	basic auth password
DEBUG	DEBUG=1 open debug mode

if WEB_USER_NAME is not empty basic auth will be open

配置文件

config file must named as conf.yaml

this file contains multi section.

the first section is docserver config,other sections are mkdoc project config ,those config's format as the same as mkdoc config.

• docserver section

名称	描述
repo	repository to clone
branch	branch to clone

• projects section

名称	描述
id	path for doc page

for example:

repo: "https://github.com/TheWinds/mkdoc.git"
branch: develop
---
id: project_1
name: mkdoc example1
desc: this doc is auto generated by [mkdoc](https://github.com/TheWinds/mkdoc)
api_base_url: "http://localhost:8080"
mime:
  in:  form
  out: json
scanner:
  - gofunc
generator:
  - docsify
args:
  enable_go_mod: true
  path: "./src"
---
id: project_2
name: mkdoc example2
desc: this doc is auto generated by [mkdoc](https://github.com/TheWinds/mkdoc)
api_base_url: "http://localhost:8080"
mime:
  in:  form
  out: json
inject:
  - name: "token"
    desc: "jwt token"
    default: "hfjdjhkklashjkfsd.hjkfsdajhkfdsj.jknsfdksf"
    scope: header
scanner:
  - gofunc
  - docdef
generator:
  - markdown
  - insomnia
  - docsify
args:
  enable_go_mod: true
  path: "./src"

例子

参考examples目录下的例子

文档

👉 Wiki

插件

插件包括3种类型Scanner、Generator、ObjectLoader,您可以自己实现这3种插件来适应自己项目中的生成需求, 下面有一些已经实现的插件。

Scanner

Scanner(扫描器)的作用是从源码中扫描注解

内置了以下扫描器:

名称	说明	链接
gofuc	从 golang func comments中扫描文档信息	🛸
docdef	从 doc schema文件中扫描文档信息	🛸

Generator

Generator(文档生成器)的作用是根据api信息生成 文档 || 测试

内置了以下生成器:

名称	说明	链接
docsify	生成docsify所需文档	🛸
markdown	生成markdown格式的文档	🛸
insomnia	生成可供insomnia导入的数据,可用于测试	🛸

ObjectLoader

ObjectLoader(Object加载器)的作用是根据类型定位信息加载Object

内置了以下Loader:

名称	说明	链接
goloader	golang sturct 类型加载	🛸