revel + swagger 文档也能互动啦
beego 从 1.3 后开始支持自动化API文档,不过,目测比较复杂,一直期望 revel 能有官方支持。
revel 确实已经有了官方支持的计划,有可能将在 0.14 版本支持,现在才 0.11.1 版本,只好自己手工撸一个出来,半自动化,但能满足基本需求了。
1. 准备
1.1 swagger-ui
swagger 是一个开源项目,swagger-ui 将符合 swagger 定义的描述规则的 Json 数据以网页形式呈现。
swagger 有在线的实例可以直接看到 swagger-ui 文档效果,如下:
swagger-ui 本身是不需要依赖任何第三方代码的,而使用 swagger-ui 实现 revel 的 API 文档仅需 swagger-ui 源码 dist 文件夹中的文件,可以如下获取:
git clone https://github.com/swagger-api/swagger-ui
然后,将 dist 路径下文件拷贝到工程目录(目录结构见下文)。
1.2 代码生成
swagger 有专门的代码生成项目 swagger-codegen,但别着急,revel 需要的不是它,是在 swagger-spec 发现的 Swagger spec generator,golang 实现、自带 swagger-ui。
go get github.com/yvasiyarov/swagger
直接命令行输入swagger
回车
支持三个级别注释:
General API info, API 通用信息,在项目入口函数所在文件写一份即可,例如 init.go
// @APIVersion 1.0.0
// @Title My Cool API
// @Description My API usually works as expected. But sometimes its not true
// @Contact api@contact.me
// @TermsOfServiceUrl http://google.com/
// @License BSD
// @LicenseUrl http://opensource.org/licenses/BSD-2-ClauseSub API Definitions, 子模块定义,每个资源定义一次
// @SubApi Order management API [/order]
// @SubApi Statistic gathering API [/cache-stats]API Operation, API 定义,需要文档化的接口函数
// @Title getOrdersByCustomer
// @Description retrieves orders for given customer defined by customer ID
// @Accept json
// @Param customer_id path int true "Customer ID"
// @Param order_id query int false "Retrieve order with given ID only"
// @Param order_nr query string false "Retrieve order with given number only"
// @Param created_from query string false "Date-time string, MySQL format. If specified, API will retrieve orders that were created starting from created_from"
// @Param created_to query string false "Date-time string, MySQL format. If specified, API will retrieve orders that were created before created_to"
// @Success 200 {array} my_api.model.OrderRow
// @Failure 400 {object} my_api.ErrorResponse Customer ID must be specified
// @Resource /order
// @Router /orders/by-customer/{customer_id} [get]
1.3 revel module
revel 支持模块,每个模块可以有独立的路由和配置文件,即 routes.go 和 app.conf,revel 负责将其与其他模块及主应用对应文件合并,详细规则可参考 revel 文档相关章节 Modules。
swagger-ui 将以 revel module 方式插入主应用,需要设计独立的路由。
1.4 目录结构
revel new revel-swagger
新建 modules 文件夹,并在其中建立 swagger-ui 文件夹,如下:
2 实现
2.1 Step 1
- 复制
yvasiyarov/swagger/swagger-ui/
路径下文件至revel-swagger/modules/swagger/swagger-ui
在
revel-swagger/modules/swagger/conf
新建routes
文件,放入如下路由GET /docs Docs.GetApiDocs
GET /docs/api/*filepath Static.ServeModule("swagger","swagger-ui")
GET /docs/:apiKey Docs.GetApiDoc在
revel-swagger/modules/swagger/app/controllers
新建apidocs.go
并实现routes
中定义的路由
2.2 Step 2
- 在主应用
app.conf
文件中添加模块引用module.swagger = you/path/to/revel-swagger/modules/swagger
- 在主应用
routes
文件中添加模块路由module:swagger
2.3 Step 3
- 使用
github.com/yvasiyarov/swagger
生成 swagger 支持的 Json 注释文件docs.go
-apiPackage
设置为主应用app/controllers
路径,路径为相对于$GOPATH/src
的相对路径-mainApiFile
设置为主应用的某个.go
文件路径,作为 swagger 通用 API 信息定义文件,同样路径为相对$GOPATH/src
的路径-output
输出路径,设置为you/path/to/revel-swagger/modules/swagger/app/controllers
,为绝对路径
在 you/path/to/revel-swagger/modules/swagger/app/controllers
生成了 docs.go
文件,此时,访问 localhost 就可以看到 swagger-ui 页面了,不过内容还是 swagger 的示例。
2.4 Step 4
init.go
添加 General API infoapp.go
添加 API 接口及注释- 修改
swager-ui/index.html
第 28 行为url: "http://127.0.0.1:9000/docs"
- 重新生成
docs.go
- 设置
-basePath=127.0.0.1:9000
- 设置
访问 http://127.0.0.1:9000
可以看到 API 的 swagger 文档了:
3 其他
yvasiyarov/swagger
支持的数据格式需要参考其项目说明- 没有找到 上传文件及参数为数组的描述方法,swagger 本身是支持的
- 示例代码放在 github
转载于:https://www.cnblogs.com/shanpow/p/4117666.html
revel + swagger 文档也能互动啦相关推荐
- 使用 Swagger 文档化和定义 RESTful API
大部分 Web 应用程序都支持 RESTful API,但不同于 SOAP API--REST API 依赖于 HTTP 方法,缺少与 Web 服务描述语言(Web Services Descript ...
- idea快速生成crud_Java / Spring:如何快速生成完整的Swagger文档CRUD REST API
idea快速生成crud 作为开发人员,我们在日常生活中经常面临的最繁琐的任务之一就是编写良好且易于理解的文档. 无论我们的文档只有几行来解释功能的核心功能,还是表明系统的来龙去脉的成熟文章都没关系. ...
- net core 3.1 swagger文档添加 不用xml配置
使用特性来描述接口而不是xml文件,使用特性可自定义接口在swaggerUI上的描述 安装nuget包:Swashbuckle.AspNetCore.SwaggerUI和Swashbuckle.Asp ...
- swagger 扫描java文档_使用Javadocs生成Swagger文档
我想为现有的一组RESTful API构建Swagger文档.我有以下要求: 读取现有的Javadoc,以便可以在Swagger文档中使用它们. 到目前为止使用上面的插件我能够实现第1点.所以对于现有 ...
- swagger文档配置
swagger文档在springboot项目中使用已经非常广泛,作为api接口管理工具 使用起来也很简单,只需要简单配置一下,就可以生成文档管理页面,在页面上管理查看api接口文档,以及进行接口调试等 ...
- swagger文档增强工具knife4j使用详解
本文从本人博客搬运,原文格式更加美观,可以移步原文阅读:swagger文档增强工具knife4j使用详解 使用原生的swagger作为接口文档,功能不够强大,并且默认的ui比较简陋,不符合大众审美.所 ...
- 设置swagger文档自动同步到YApi
SpringBoot项目引入swagger文档后,每次都要手工维护接口到YApi很麻烦,有没有设置自动化同步的办法?操作如下: 进入YApi后添加项目 添加完项目后,点击设置,配置基本项目信息,由于我 ...
- Django Swagger文档库drf-spectacular
在使用DRF的时候,通常的文档有:默认文档RestFrameWork.CoreAPI.Swagger,Swagger是最流行的API文档库,在绝大多数服务端开发中都有用到,之前我们使用了CoreAPI ...
- Swagger 文档中文版,国产API 文档工具使用教程
swagger文档.swagger ui 在后端开发中使用非常广泛,接口文档开发和代码生成等功能非常好用. 但swagger是付费的产品,而免费版的swagger 文档需要自己去配置,流程非常复杂,因 ...
- java附魔_给你的Swagger文档换套附魔皮肤吧
本文将为您描述给你的Swagger文档换套附魔皮肤吧,具体完成步骤:前言 相信无论是前端或是后端的程序员对Swagger都不怎么陌生,没有用过应该也听说过 Swagger 是一个规范和完整的框架,用于 ...
最新文章
- (初学必看)deep graph library(dgl)库的入门引导
- 解读Android LOG机制的实现
- 中考计算机flash试题及答案,2015中考信息技术试题Flash操作题2-25(终)
- 减小Gcc编译程序的体积
- ADO.NETv2.0的一些特征
- 数据整理—dplyr包(filter系列)
- 原生javascript知识点
- 《纽约时报》:乔布斯最后的日子 与家人相伴
- SharePoint开发错误—列表自定义表单出现“未将对象引用设置到对象的实例”
- java基础_day02
- Shell脚本里的双冒号是什么意思
- mysql数据库rpm包安装_Linux rpm包安装MySQL数据库问题总结
- 小甲鱼python课后习题【1,2,3,4,5】
- Python3制作网易云音乐下载器!付费的你猜能下载吗!
- Android蓝牙开发系列文章-蓝牙设备类型知多少?
- MES系统的应用(中)
- python3下载mapbox矢量切片
- C#发送企业内部邮件
- android开发编辑wordpress,如何用WordPress 开发基于安卓的APP接口?
- 【Alpha】阶段第九次Scrum Meeting