swagger接口文档生成
[!TIP] 使用接口生成工具，自动为bus接口生成
swagger.json接口api文件，实现接口的统一管理。[!question] 【缺陷】接口并非是全自动的生成方式，需要配置每个接口的参数和响应信息，此工具主要目的是为了简化接口文档的编写和测试用例。
function
├── tag -- 标签
├── swagger -- 是否显示接口，1 是，0 否，默认 1
├── method -- 请求方法（POST，GET）
├── contentType -- 请求类型，FORM 表单提交 默认,JSON json提交方式
├── params -- 参数处理集合
| ├── param -- 某个参数处理
| | ├── type -- 参数类型，默认 string
| | ├── example -- 参数示例值
| | ├── description -- 参数描述，如果为空默认为name
| result -- 响应参数
| ├── type -- 类型
| ├── example -- 示例值
| ├── description -- 描述
| ├── property -- 属性列表
| ├ ├── name -- 属性名称
| ├ ├── type -- 属性类型
| ├ ├── description -- 属性描述
| ├ ├── example -- 属性示例值
配置说明
- 请求参数需要在功能号文件夹中
functions - 响应参数需要在文件夹中
functions-results
[!TIP] 请求参数和响应参数为什么分开配置，没有在同一个文件里面？
分开配置，主要是为了解决配置文件单个太大的问题，而且接口文档只有在开发过程中使用到，所以分开配置。
请求参数配置
配置示例
可以参考以下demo来配置接口文档，主要关注param中的配置项。
type：参数类型，默认stringexample：参数值示例description：参数的描述信息，为空默认显示name的值- 如果
value属性中有配置值，那么这个参数不属于接口调用参数
<function id="D1000" type="s">
<params>
<param name="性别" id="sex" type="integer" example="1" description="性别，1 男，2 女"/>
<param name="年龄" id="age" type="integer"/>
<param id="ip" name="ip" value="$ip()"></param>
</params>
<resource>DemoService.select</resource>
<desc>新增</desc>
</function>
- 生成后的接口文档，json示例
{
"sex": 1,
"age": 0
}
标签/分组
由于接口比较多的时候，如果没有对接口进行分组，看的就比较累，在接口文档中，很难找到对应的接口。
可以通过定义tag来定义标签名称，同一个标签将会在同一个分类下。
<function id="D1000" type="s" tag="用户相关接口">
<params>
<param name="性别" id="sex" type="integer" example="1" description="性别，1 男，2 女"/>
<param name="年龄" id="age" type="integer"/>
<param id="ip" name="ip" value="$ip()"></param>
</params>
<resource>DemoService.select</resource>
<desc>新增</desc>
</function>
部分功能不生成接口文档
对于有些功能是内部微服务调用，不想生成接口文档，可以通过配置swagger="0"来过滤接口生成。
<function id="D1000" type="s" swagger="0">
<params>
<param name="性别" id="sex" type="integer" example="1" description="性别，1 男，2 女"/>
<param name="年龄" id="age" type="integer"/>
<param id="ip" name="ip" value="$ip()"></param>
</params>
<resource>DemoService.select</resource>
<desc>新增</desc>
</function>
响应参数配置
[!question] 如果接口没有返回对象，可以不用写。
普通类型
返回单一的类型
result：返回对象属性配置type：类型，普通类型为string，integer，long，float，double，byte，date，dateTimeexample：参数示例值description：参数描述
<function id="D1000" tag="订单">
<result type="integer" example="" description="订单id">
</result>
</function>
json示例
{
"errorNo": 0,
"errorInfo": "string",
"data": 0
}
对象
返回一个对象
result：返回对象属性配置type：类型，普通类型为objectexample：参数示例值description：参数描述property：对象中的属性列配置
<function id="D1002" tag="支付">
<result type="object" example="" description="列表">
<property name="dddddd" type="string" description="测试1"></property>
<property name="xx" type="long" description="测试2"></property>
</result>
</function>
json示例
{
"errorNo": 0,
"errorInfo": "string",
"data": {
"dddddd": "string",
"xx": 0
}
}
列表对象
返回一个列表，列表中是复杂的对象
result：返回对象属性配置type：类型，列表对象类型为objectListexample：参数示例值description：参数描述property：对象中的属性列配置
<function id="D1002" tag="支付">
<result type="objectList" example="" description="列表">
<property name="dddddd" type="string" description="测试1"></property>
<property name="xx" type="long" description="测试2"></property>
</result>
</function>
json示例
{
"errorNo": 0,
"errorInfo": "string",
"data": [{
"dddddd": "string",
"xx": 0
}]
}
普通类型列表
返回一个列表，列表中是简单的类型，例如返回一个int集合
result：返回对象属性配置type：类型，普通类型列表为stringList，integerList，longListexample：参数示例值description：参数描述
<function id="D1002" tag="支付">
<result type="stringList" example="" description="列表">
</result>
</function>
json示例
{
"errorNo": 0,
"errorInfo": "string",
"data": ["string"]
}
分页对象
返回一个分页结果对象
result：返回对象属性配置type：类型，分页类型为pageexample：参数示例值description：参数描述property：对象中的属性列配置
<function id="D1001" tag="支付">
<result type="page" example="" description="">
<property name="dddddd" type="string" description="测试1"></property>
<property name="xx" type="long" description="测试2"></property>
</result>
</function>
json示例
{
"errorNo": 0,
"errorInfo": "string",
"data": {
"pageNum": 0,
"pageSize": 0,
"total": 0,
"pages": 0,
"list": [
{
"dddddd": "string",
"xx": 0
}
]
}
}
复杂类型嵌套
返回一个复杂类型组合嵌套
result：返回对象属性配置type：类型，分页类型为pageexample：参数示例值description：参数描述property：对象中的属性列配置
可以通过指定type类型指定复杂对象，property中嵌套属性即可。
<function id="D1001" tag="支付">
<result type="page" example="" description="">
<property name="dddddd" type="string" description="测试1"></property>
<property name="xx" type="long" description="测试2"></property>
<property name="list" type="objectList" description="列表">
<property name="code" type="string" description="代码"></property>
<property name="name" type="string" description="名称"></property>
</property>
</result>
</function>
json示例
{
"errorNo": 0,
"errorInfo": "string",
"data": [
{
"dddddd": "string",
"xx": 0,
"list": [
{
"code": "string",
"name": "string"
}
]
}
]
}
生成接口文件
引入jar包
<dependency>
<groupId>com.wueasy</groupId>
<artifactId>wueasy-swagger</artifactId>
<version>最新版本</version>
</dependency>
接口配置信息
wueasy:
swagger:
info: #基础信息
title: 个人中心接口 #标题
description: 个人中心接口列表 #描述
version: 1.0.0 #版本
servers: #接口列表
- url: http://49.234.40.74:10100 #接口地址
description: 测试1 #描述
启动类
执行后将会在/src/main/resources文件夹中生成swagger.json
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;
import com.wueasy.Application;
import com.wueasy.swagger.util.SwaggerUtil;
/**
* @author: fallsea
* @version 1.0
*/
@RunWith(SpringJUnit4ClassRunner.class)
@SpringBootTest(classes=Application.class)
public class ApplicationTests {
/**
* 测试
* @author: fallsea
*/
@Test
public void testObj() {
SwaggerUtil.generate();
}
}
接口部署
经过接口生成后，最后需要部署swagger接口环境，通过静态文件部署即可。
下载 swagger-ui
首选需要下载
swagger-ui，可以通过下面的地址进行下载最新版本。https://github.com/swagger-api/swagger-ui/releases
获取到ui中已经生成好的文件夹
dist目录打开
index.html，修改里面的jsonurl地址即可。改为自己的地址。
window.onload = function() {
// Begin Swagger UI call region
const ui = SwaggerUIBundle({
url: "https://petstore.swagger.io/v2/swagger.json",
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: "StandaloneLayout"
})
// End Swagger UI call region
window.ui = ui
}