偏头痛杨

所有文章全部原创,联系作者请加QQ:122291891,技术讨论请加QQ群:4794056。

偏头痛杨的springfox-swagger自动接口文档生成装置入门
前戏
作为后端程序员的我们,通常我们要构建API服务,要写服务端接口,自然少不了写接口文档,
否则就要口述,但口述的痛点也很多。

一般情况下,我们的接口文档要写两份:
1.给前端团队看的word接口文档。
2.给后端团队看的写在代码中的注释。

一样的事情做了两遍,让后端程序员不爽,繁琐且无趣,稍有遗漏就会造成接口文档与接口不同步的情况,
为引发线上bug埋下伏笔。

那么有没有一种解决方案可以解决写两次的痛点呢?目前市面上大致有两种方案:
1.小幺鸡、sosoapi等:需要维护代码和文档两个地方,不过脱离项目,功能比较多,适合外部文档解决方案。
2.swagger:注解生成,不用维护两套,功能比较单一,依赖项目,有少量代码入侵,适合内部文档解决方案。


什么是Swagger?
Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。
Swagger可以通过代码&注释自动生成漂亮的在线API页面,甚至可以提供运行示例并实时同步。
Swagger会扫描配置与注解自动生成一份json数据,而swagger官方也提供了swagger-ui来做通常的展示。
 

使用方法

注意:
~swagger2.5必须需要spring4的支持,否则会报错。
~如果有/src/test/java的配置文件,则需要同步修改,否则会启动报错。

1.在项目的pom.xml中添加依赖
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.5.0</version>
</dependency>

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.5.0</version>
</dependency>

2.编写swagger的配置类(唯一的一个)
/**
* Title: swagger核心配置类(就这一个).<br>
* Description: MySwaggerConfig<br>
*/
@Configuration
@EnableSwagger2
public class MySwaggerConfig {
    /**
     * Title: 构建swagger.<br>
     * Description: 这个方法起什么名字都可以,主要是注解起作用<br>
     *
     * @category buildDocket
     * @return
     */
    @Bean
    public Docket buildDocket() {
        String env = "dev";//判断当前环境是什么,通过缓存拿。
        Docket docket = null;
        if("dev".equals(env)){
            // 添加http请求头
            ParameterBuilder tokenPar = new ParameterBuilder();
            List<Parameter> pars = new ArrayList<Parameter>();
            tokenPar.name("token").description("令牌").modelRef(new ModelRef("string")).parameterType("header")
                    .required(false).build();
            pars.add(tokenPar.build());

            docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(buildApiInf())// 构建信息
                    .select() // 选择那些路径和api会生成document
                    .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))//只扫描有注解的
                    //.apis(RequestHandlerSelectors.any()) 扫描所有类
                    //.apis(RequestHandlerSelectors.basePackage("example.web.controller"))//要扫描的API(Controller)基础包
                    .paths(PathSelectors.any()) // 对所有路径进行监控
                    .build().globalOperationParameters(pars);// 添加header
        }
        
        return docket;
        
    }

    private ApiInfo buildApiInf() {
        String description = "aaaa<br>bbbb<br>通用返回码都放在这里,可以使用便利枚举类的形式形成一个字符串放到这里";
        return new ApiInfoBuilder().title("xxxx项目的API文档").description(description)
                .contact(new Contact("wesley", "http://blog.csdn.net/piantoutongyang", "171757607@qq.com"))
                .version("2.0.0").build();
    }
}


3.spring配置文件
<?xml version="1.0" encoding="UTF-8"?>
<!-- Application context definition for PetClinic on JDBC. -->
<beans xmlns="http://www.springframework.org/schema/beans"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">

      <bean class="com.swagger.doc.MySwaggerConfig" />
</beans>

4.spring-mvc配置文件
<?xml version="1.0" encoding="UTF-8"?>
<!-- Application context definition for PetClinic on JDBC. -->
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:context="http://www.springframework.org/schema/context"
       xmlns:mvc="http://www.springframework.org/schema/mvc"
       xsi:schemaLocation="http://www.springframework.org/schema/mvc http://www.springframework.org/schema/mvc/spring-mvc-3.2.xsd
            http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
            http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd">

    <mvc:annotation-driven/>

    <context:component-scan base-package="com.swagger.doc"/>

    <mvc:default-servlet-handler/>
</beans>


swagger注解解释
注解
描述
@Api
标记在类名上,表示这个类是一个swagger资源,只有标注了这个标签相应的api信息才能展现出来,
其中包括可以设置:
description:描述Controller类的作用。  

@ApiOperation
标记&描述具体的方法。一个@API下,可以有多个@ApiOperation
(一个类中有多个方法),
其中包括可以设置:
value:接口名称
notes:接口描述,换行用</br> HMLT的标签就行了
 
@ApiResponses
在一个@ApiOperation下,可以通过@ApiResponses描述API操作可能出现的异常情况。
@ApiResponses用来组合@ApiResponse,暂无用。
@ApiResponse
返回值,该类主要有code值与message两个属性,
code值必须是http 返回code值,默认会有200,404等,不能单独使用,
必须和@ApiResponses一起使用。暂无用。swagger会根据返回类型与返回值自动生成。

@ApiParam
用于描述该API操作接收的参数类型,value用于描述参数,
required指明参数是否为必须。
定义具体的请求参数,类似@RequestParam参数,直接在方法参数上使用。
@ApiImplicitParams
组合一组@ApiImplicitParam,跟ApiParam类似,但他是写在方法的上面,
而不是形参的前面,要更复杂一些。
无法描述较复杂类型的数据对象,建议还是用ApiParam。
@ApiImplicitParam
描述具体的请求参数,比如具体的响应方法的参数为HttpServletRequest时,
我会从该参数中取一些请求参数,
则可以通过该方法单独定义参数.见下面的具体说明,该参数不能单独使用,
必须和@ApiImplicitParams一起使用。
使用ApiImplicitParam时,需要指定paramType,
这样也便于swagger ui 生成参数的输入格式。
paramType有五个可选值 : path, query, body, header, form。
@ApiModel
提供对请求参数与返回结果中的model的定义,实体bean需要自动生成注解。
@ApiModelProperty
提供对请求参数与返回结果中的model的属性定义,可以使用example做默认值,实体bean需要自动生成注解。
@ApiIgnore
使用这个注解忽略这个接口


一个例子

Controller
@Api(description = "controller的中文解释")
@Controller
public class YangController {

    @ResponseBody
    @ApiOperation(value = "接口名称-增111", notes = "接口描述-增,作者:alex")
    @RequestMapping(value = "/yang", method = RequestMethod.POST, produces = MediaType.APPLICATION_JSON_VALUE)
    public CommonJsonObject<Object> insertYang(@ApiParam(value = "yang参数", required = true) @RequestBody Yang yang) {
        System.out.println("正在创建111");
        System.out.println(yang.getYangAge());
        System.out.println(yang.getYangId());
        System.out.println(yang.getYangName());

        return new CommonJsonObject<Object>();
    }

    @ApiOperation(value = "接口名称-删", notes = "接口描述-删,作者:alex")
    @ResponseBody
    @RequestMapping(value = "/yang", method = RequestMethod.DELETE, produces = MediaType.APPLICATION_JSON_VALUE)
    public CommonJsonObject<Object> deleteYang(
            @ApiParam(name = "yangId", required = true, value = "杨Id") String yangId) {
        System.out.println("正在删除");
        System.out.println(yangId);

        return new CommonJsonObject<Object>();
    }

    @ApiOperation(value = "接口名称-改", notes = "接口描述-改,作者:alex")
    @ResponseBody
    @RequestMapping(value = "/yang", method = RequestMethod.PUT, produces = MediaType.APPLICATION_JSON_VALUE)
    public CommonJsonObject<Object> updateYang(@ApiParam(value = "yang参数", required = true) @RequestBody Yang yang) {
        System.out.println("正在修改");
        System.out.println(yang.getYangAge());
        System.out.println(yang.getYangId());
        System.out.println(yang.getYangName());
        return new CommonJsonObject<Object>();
    }
    
    @ResponseBody
    @ApiOperation(value = "接口名称-查单个", notes = "接口描述-查单个,作者:alex")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "yangId", value = "杨Id", required = true, dataType = "String",paramType = "path"),
        @ApiImplicitParam(name = "demoId", value = "做测试用的没有意义,多参数", required = false, dataType = "String",paramType = "query")
    })
    @RequestMapping(value = "/yang/{yangId}", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_VALUE)
    public CommonJsonObject<Yang> findYangById(@PathVariable String yangId,String demoId) {
        System.out.println("正在查询");
        System.out.println(yangId);
        
        Yang yang = new Yang();
        yang.setYangAge(123);
        yang.setYangId(yangId);
        yang.setYangName("hahaha");
        
        CommonJsonObject<Yang> json = new CommonJsonObject<Yang>();
        json.setData(yang);

        return json;
    }
    
    
    @ResponseBody
    @ApiOperation(value = "接口名称-查列表", notes = "接口描述-查列表,作者:alex")
    @RequestMapping(value = "/yangs", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_VALUE)
    public CommonJsonObject<List<Yang>> findYangList() {
        System.out.println("正在查询xxxxxxxx");
        
        Yang yang1 = new Yang();
        yang1.setYangAge(123);
        yang1.setYangId("123");
        yang1.setYangName("hahaha");
        
        Yang yang2 = new Yang();
        yang2.setYangAge(123);
        yang2.setYangId("123");
        yang2.setYangName("hahaha");
        
        List<Yang> yangList = new ArrayList<Yang>();
        yangList.add(yang1);
        yangList.add(yang2);
        
        CommonJsonObject<List<Yang>> json = new CommonJsonObject<List<Yang>>();
        json.setData(yangList);

        return json;
    }
    
    @ResponseBody
    @RequestMapping(value = "/noshow", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_VALUE)
    public CommonJsonObject<List<Yang>> noshow() {
        /**
         * 没有没有写@ApiOperation标签则在swagger-ui中显示
         */
        System.out.println("正在查询");
        
        Yang yang1 = new Yang();
        yang1.setYangAge(123);
        yang1.setYangId("123");
        yang1.setYangName("hahaha");
        
        Yang yang2 = new Yang();
        yang2.setYangAge(123);
        yang2.setYangId("123");
        yang2.setYangName("hahaha");
        
        List<Yang> yangList = new ArrayList<Yang>();
        yangList.add(yang1);
        yangList.add(yang2);
        
        CommonJsonObject<List<Yang>> json = new CommonJsonObject<List<Yang>>();
        json.setData(yangList);

        return json;
    }
}


通用返回对象,必须要用泛型,否则swagger不认你的嵌套对象,无法解析其中文含义。
@ApiModel(value="CommonJsonObject(通用返回模型)")
public class CommonJsonObject<T> {
      // 默认200为应答成功
      @ApiModelProperty(value="返回码",required=true,example="200")
      private int code = 200;
      @ApiModelProperty(value="返回数据",required=true)
      private T data;
      @ApiModelProperty(value="返回描述",required=true)
      private String msg;

      public CommonJsonObject(){

      }

      public CommonJsonObject(int code) {
            this.code = code;
      }

      public CommonJsonObject(int code, T data) {
            this.data = data;
            this.code = code;
      }

      public CommonJsonObject(int code, T data, String msg) {
            this.data = data;
            this.code = code;
            this.msg = msg;
      }

      public int getCode() {
            return code;
      }

      public void setCode(int code) {
            this.code = code;
      }

      public T getData() {
            return data;
      }

      public void setData(T data) {
            this.data = data;
      }

      public String getMsg() {
            return msg;
      }

      public void setMsg(String msg) {
            this.msg = msg;
      }

}

参数bean
import io.swagger.annotations.ApiModelProperty;

@ApiModel(value="Yang(杨模型)")
public class Yang {
      @ApiModelProperty(value="杨ID",required=true,example="12345")
    private String yangId;
      @ApiModelProperty(value="杨用户名",required=true,example="abcde")
    private String yangName;
      @ApiModelProperty(value="杨年龄",required=false,example="16")
    private Integer yangAge;

      public String getYangId() {
            return yangId;
      }
      public void setYangId(String yangId) {
            this.yangId = yangId;
      }
      public String getYangName() {
            return yangName;
      }
      public void setYangName(String yangName) {
            this.yangName = yangName;
      }
      public Integer getYangAge() {
            return yangAge;
      }
      public void setYangAge(Integer yangAge) {
            this.yangAge = yangAge;
      }
}

启动服务后调用这个地址访问接口文档:
http://localhost:xxxx/swagger-ui.html

可以获得生成上述文档的Swagger JSON定义:
http://localhost:xxxx/v2/api-docs



注意事项
1.要注意安全性,在生产环境的外网下是必须不能被访问到swagger-ui.html的。

2.swagger如何能自动生成&更新mock数据呢?
-目前得知是需要后端开发人员自己return或者写example,总之要手写,不能做到自动生成mock数据。
-如果必须是这样,那么前端可以去掉之前的mock.js流程,直接调用后端的假接口
(没有实现逻辑的接口,只提供假数据),那这些假接口就是前后端的“契约”。
如果后端的接口发生变化,前端第一时间会知道,促使一次前后端沟通,其他的解决方案以后再看。

(如果能做到自动生成mock数据,则前端依然可以玩他的那套mock.js,swagger来提供json格式的mock数据)

3.把功能相似的接口抽成一个controller,不要超过600行,自己划分不同的controller。

4.在开发的过程中,如果前后端有任意一方需要修改数据结构等造成接口变化,需要第一时间通知对方, 
以及通知测试。测试的测试用例有可能会改,不要拖着,否则问题会在前后端集成时彻底爆发。

5.前端也要有自己的单元测试用例,以及构建前端项目时,自动跑测试用例,调用后端接口。
这样接口发生变动后会第一时间爆发,而不是拖到生产环境。

阅读更多
版权声明:偏头痛杨:本文为博主原创文章,未经博主允许不得转载,版权必究! https://blog.csdn.net/piantoutongyang/article/details/79959725
个人分类: 项目管理
想对作者说点什么? 我来说一句

没有更多推荐了,返回首页

不良信息举报

偏头痛杨的springfox-swagger自动接口文档生成装置入门

最多只允许输入30个字

加入CSDN,享受更精准的内容推荐,与500万程序员共同成长!
关闭
关闭