偏头痛杨的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中添加依赖

  io.springfox

  springfox-swagger2

  2.5.0

  io.springfox

  springfox-swagger-ui

  2.5.0

2.编写swagger的配置类（唯一的一个）

/**

* Title: swagger核心配置类（就这一个）.

* Description: MySwaggerConfig

*/

@Configuration

@EnableSwagger2

public class MySwaggerConfig {

    /**

     * Title: 构建swagger.

     * Description: 这个方法起什么名字都可以，主要是注解起作用

     *

     * @category buildDocket

     * @return

     */

    @Bean

    public Docket buildDocket() {

        String env = "dev";//判断当前环境是什么，通过缓存拿。

        Docket docket = null;

        if("dev".equals(env)){

            // 添加http请求头

            ParameterBuilder tokenPar = new ParameterBuilder();

            List pars = new ArrayList();

            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
bbbb
通用返回码都放在这里,可以使用便利枚举类的形式形成一个字符串放到这里";

        return new ApiInfoBuilder().title("xxxx项目的API文档").description(description)

                .contact(new Contact("wesley", " http://blog.csdn.net/piantoutongyang ", " [email protected] "))

                .version("2.0.0").build();

    }

}

3.spring配置文件

         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">

      

4.spring-mvc配置文件

       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">

   

   

   

---

swagger注解解释

注解	描述
@Api	标记在类名上，表示这个类是一个swagger资源，只有标注了这个标签相应的api信息才能展现出来， 其中包括可以设置： description：描述Controller类的作用。
@ApiOperation	标记&描述具体的方法。一个@API下，可以有多个@ApiOperation （一个类中有多个方法）， 其中包括可以设置： value：接口名称 notes：接口描述，换行用 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