swagger接口文档生成

[!TIP] 使用接口生成工具，自动为bus接口生成swagger.json接口api文件，实现接口的统一管理。

[!question] 【缺陷】接口并非是全自动的生成方式，需要配置每个接口的参数和响应信息，此工具主要目的是为了简化接口文档的编写和测试用例。

function
├── tag -- 标签
├── swagger -- 是否显示接口，1 是，0 否，默认 1
├── params -- 参数处理集合
|    ├── param -- 某个参数处理
|    |      ├── type -- 参数类型，默认 string
|    |      ├── example -- 参数示例值
|    |      ├── desc -- 参数描述，如果为空默认为name
├── results -- 响应参数集合
|    ├── result -- 响应参数
|    |      ├── key -- 属性key，默认为data
|    |      ├── type -- 类型
|    |      ├── example -- 示例值
|    |      ├── description -- 描述
|    |      ├── property -- 属性列表
|    |      ├   ├── name -- 属性名称
|    |      ├   ├── type -- 属性类型
|    |      ├   ├── description -- 属性描述
|    |      ├   ├── example -- 属性示例值

配置说明

请求参数需要在功能号文件夹中functions
响应参数需要在文件夹中functions-results

[!TIP] 请求参数和响应参数为什么分开配置，没有在同一个文件里面？

分开配置，主要是为了解决配置文件单个太大的问题，而且接口文档只有在开发过程中使用到，所以分开配置。

请求参数配置

配置示例

可以参考以下demo来配置接口文档，主要关注param中的配置项。

type：参数类型，默认string
example：参数值示例
desc：参数的描述信息，为空默认显示name的值
如果value属性中有配置值，那么这个参数不属于接口调用参数

<function id="D1000" type="s">
    <params>
        <param name="性别" id="sex" type="integer" example="1" desc="性别，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" desc="性别，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" desc="性别，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] 如果接口没有返回对象，可以不用写。

普通类型

返回单一的类型

results：配置返回的对象集合
result：返回对象属性配置
- key：属性key，默认data
- type：类型，普通类型为string，integer，long，float，double，byte，date，dateTime
- example：参数示例值
- description：参数描述

<function id="D1000" tag="订单">
    <results>
        <result key="data" type="integer" example="" description="订单id">
        </result>
    </results>
</function>

json示例

{
  "errorNo": 0,
  "errorInfo": "string",
  "results": {
    "data": 0
  }
}

对象

返回一个对象

results：配置返回的对象集合
result：返回对象属性配置
- key：属性key，默认data
- type：类型，普通类型为object
- example：参数示例值
- description：参数描述
- property：对象中的属性列配置

<function id="D1002" tag="支付">
    <results>
        <result key="data" type="object" example="" description="列表">
            <property name="dddddd"  type="string" description="测试1"></property>
            <property name="xx"  type="long" description="测试2"></property>
        </result>
    </results>
</function>

json示例

{
  "errorNo": 0,
  "errorInfo": "string",
  "results": {
    "data": {
        "dddddd": "string",
        "xx": 0
      }
  }
}

列表对象

返回一个列表，列表中是复杂的对象

results：配置返回的对象集合
result：返回对象属性配置
- key：属性key，默认data
- type：类型，列表对象类型为objectList
- example：参数示例值
- description：参数描述
- property：对象中的属性列配置

<function id="D1002" tag="支付">
    <results>
        <result key="data" type="objectList" example="" description="列表">
            <property name="dddddd"  type="string" description="测试1"></property>
            <property name="xx"  type="long" description="测试2"></property>
        </result>
    </results>
</function>

json示例

{
  "errorNo": 0,
  "errorInfo": "string",
  "results": {
    "data": [{
        "dddddd": "string",
        "xx": 0
      }]
  }
}

普通类型列表

返回一个列表，列表中是简单的类型，例如返回一个int集合

results：配置返回的对象集合
result：返回对象属性配置
- key：属性key，默认data
- type：类型，普通类型列表为stringList，integerList，longList
- example：参数示例值
- description：参数描述

<function id="D1002" tag="支付">
    <results>
        <result key="data" type="stringList" example="" description="列表">
        </result>
    </results>
</function>

json示例

{
  "errorNo": 0,
  "errorInfo": "string",
  "results": {
    "data": ["string"]
  }
}

分页对象

返回一个分页结果对象

results：配置返回的对象集合
result：返回对象属性配置
- key：属性key，默认data
- type：类型，分页类型为page
- example：参数示例值
- description：参数描述
- property：对象中的属性列配置

<function id="D1001" tag="支付">
    <results>
        <result key="data" type="page" example="" description="">
            <property name="dddddd"  type="string" description="测试1"></property>
            <property name="xx"  type="long" description="测试2"></property>
        </result>
    </results>
</function>

json示例

{
  "errorNo": 0,
  "errorInfo": "string",
  "results": {
    "data": {
      "pageNum": 0,
      "pageSize": 0,
      "total": 0,
      "pages": 0,
      "list": [
        {
          "dddddd": "string",
          "xx": 0
        }
      ]
    }
  }
}

复杂类型嵌套

返回一个复杂类型组合嵌套

results：配置返回的对象集合
result：返回对象属性配置
- key：属性key，默认data
- type：类型，分页类型为page
- example：参数示例值
- description：参数描述
- property：对象中的属性列配置

可以通过指定type类型指定复杂对象，property中嵌套属性即可。

<function id="D1001" tag="支付">
    <results>
        <result key="data" 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>
    </results>
</function>

json示例

{
  "errorNo": 0,
  "errorInfo": "string",
  "results": {
    "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
}

swagger接口文档生成

swagger接口文档生成

配置说明

请求参数配置

配置示例

标签/分组

部分功能不生成接口文档

响应参数配置

普通类型

对象

列表对象

普通类型列表

分页对象

复杂类型嵌套

生成接口文件

引入jar包

接口配置信息

启动类

接口部署

results matching ""

No results matching ""