API接口markdown文档生成工具

salary · · 724 次点击 · · 开始浏览    

# 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接口文件: ![html-1.png](https://static.golangjob.cn/221108/c896927a06c83f8eaa1e1c6d77630def.png) ![html-2.png](https://static.golangjob.cn/221108/00d0bff34e3761ed8ff6a4fea25d1a80.png) ![html-3.png](https://static.golangjob.cn/221108/e836dbb96e5e6c3e7e875f52c4cd10be.png) ## markdown接口文件: ![markdown-1.png](https://static.golangjob.cn/221108/03c7c37cb55b829b121c1f7c1f7eb165.png) ![markdown-2.png](https://static.golangjob.cn/221108/c322caac9c17196547c0a02922d80b60.png) # github: https://github.com/Slary1260/createapimarkdown 求支持,谢谢~

有疑问加站长微信联系(非本文作者))

入群交流(和以上内容无关):加入Go大咖交流群,或添加微信:liuxiaoyan-s 备注:入群;或加QQ群:692541889

724 次点击  ∙  1 赞  
加入收藏 微博
暂无回复
添加一条新回复 (您需要 登录 后才能回复 没有账号 ?)
  • 请尽量让自己的回复能够对别人有帮助
  • 支持 Markdown 格式, **粗体**、~~删除线~~、`单行代码`
  • 支持 @ 本站用户;支持表情(输入 : 提示),见 Emoji cheat sheet
  • 图片支持拖拽、截图粘贴等方式上传