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:参数类型,默认string
  • example:参数值示例
  • 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:类型,普通类型为stringintegerlongfloatdoublebytedatedateTime
    • example:参数示例值
    • description:参数描述
<function id="D1000" tag="订单">
    <result type="integer" example="" description="订单id">
    </result>
</function>

json示例

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

对象

返回一个对象

  • result:返回对象属性配置
    • type:类型,普通类型为object
    • example:参数示例值
    • 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:类型,列表对象类型为objectList
    • example:参数示例值
    • 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:类型,普通类型列表为stringListintegerListlongList
    • example:参数示例值
    • description:参数描述
<function id="D1002" tag="支付">
    <result type="stringList" example="" description="列表">
    </result>
</function>

json示例

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

分页对象

返回一个分页结果对象

  • result:返回对象属性配置
    • type:类型,分页类型为page
    • example:参数示例值
    • 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:类型,分页类型为page
    • example:参数示例值
    • 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接口环境,通过静态文件部署即可。

  1. 下载 swagger-ui

    首选需要下载swagger-ui,可以通过下面的地址进行下载最新版本。

    https://github.com/swagger-api/swagger-ui/releases

  1. 获取到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
}
Copyright © wueasy.com 2017-2020 all right reserved,powered by Gitbook未经允许,禁止以任何形式传播 修订时间: 2020-03-25

results matching ""

    No results matching ""