# API接口markdown文档生成工具
通过api的请求对象、返回对象，自动生成对应的API接口文档。
使得开发人员接口开发完成时，或接口维护后，无需再更新api文档。
## 编码工具的原因
目前使用比较多的是swagger，但是swagger依旧有一些缺点。
来自网友的总结：
```
如果是与服务端代码集成，直接嵌入到工程代码中，侵入性比较大。将文档参数和应用参数杂糅在一起，不易阅读，而且比较依赖于项目，无法独立部署。项目挂掉，文档也无法访问。给后期代码维护增加难度。
如果直接编辑json文档，则难度比较大。即使是官网的在线编辑，功能也比较弱，提示功能差劲。很多时候在编辑预览中没问题，导出来部署就显示不正常。而且不支持多人编辑，只能一次一个人改，部署相当不方便。
用户体验，无论请求还是响应，无法方便的输入自定义json格式。特别是多层嵌套，异常繁琐。
```
我个人觉得swagger生成的页面展示不够直观。需要点击相应的按钮，才能查看接口的参数与返回值。
因此在日常工作中，需要一个简单、便捷的API接口生成工具。根据接口的定义，自动生成对应的接口文档，且后续维护不再需要手动更新接口文档。于是开始编写该工具。
## 1.特性
### 1.1.嵌套层数
请求对象和返回对象目前只支持三层嵌套(暂不支持指针对象嵌套):Result->ActivityListResponse->ActivityListDetail
```
type Result struct {
Data interface{} `json:"data" validate:"required"`
}
type ActivityListResponse struct {
Details []ActivityListDetail `json:"details" validate:"required,详细信息"`
}
type ActivityListDetail struct {
}
```
### 1.2.支持类型
请求对象、返回对象：指针、结构体和切片(slice)。
对象字段：结构体、匿名结构体、有符号整型、无符号整型、字符串、bool，浮点型(float32,float64)
### 1.3.可自定义markdown tag 标识(默认值为validate)
例：
修改前：
```
TotalCount int64 `json:"totalCount" validate:"required,总数"`
```
修改后：
```
TotalCount int64 `json:"totalCount" doc:"required,总数"`
```
代码设置
```
doc := document.NewDocument("接口文档", "1.0", "api/")
doc.SetMdKey("doc")
```
### 1.4.支持markdown转html
```
md := markdown.New(doc, markdown.WithMd2Html(true))
```
### 1.5.支持传入解析好的API结构体数据
```
doc := document.NewDocument("api/", document.WithParseReq(false), document.WithParseRsq(false))
reqFields, err := doc.ParseReqOrRsp(req)
if err != nil {
log.Panic(err)
}
rspFields, err := doc.ParseReqOrRsp(rsp)
if err != nil {
log.Panic(err)
}
item.ReqFields = reqFields
item.RspFields = rspFields
err = doc.AddDocItem(item)
if err != nil {
log.Panic(err)
}
```
## 2.gin自动注册路由
根据gin自动注册的路由参数，自动生成API接口文档。
# 接口文档 demo
## html接口文件:
## markdown接口文件:
# github: https://github.com/Slary1260/createapimarkdown
求支持，谢谢~
有疑问加站长微信联系（非本文作者））
