# spring boot / cloud (三) 集成springfox-swagger2构建在线API文档

##前言

###不能同步更新API文档会有什么问题?

>理想情况下,为所开发的服务编写接口文档,能提高与周边系统对接联调的效率.但前提条件是,服务和API文档必须是同步更新的,如果不能保证同步,那接口文档就会流于形式,不仅不能起到应有的作用,甚至某些情况下,甚至会误导对接的系统,导致更低效率的沟通.

##思路

- 根据现有的服务定义来自动生成接口文档

##实现

###1.pom.xml集成springfox-swagger2


``` xml
	<!-- swagger2 -->
    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>${springfox-swagger2.version}</version>
    </dependency>
    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
      <version>${springfox-swagger2.version}</version>
    </dependency>
```

###2.创建Swagger2Config类

``` java
@Configuration
@EnableSwagger2
public class Swagger2Config {


}
```


###3.配置Bean

``` java
  @Bean
  public WebMvcConfigurerAdapter addResourceHandlers() {
    return new WebMvcConfigurerAdapter() {
      @Override
      public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
            .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
            .addResourceLocations("classpath:/META-INF/resources/webjars/");
      }
    };
  }
```

注意点 : 版本号和项目名称可在配置文件中定义(从pom中取)

``` java
 @Bean
  public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
        .apis(RequestHandlerSelectors.basePackage("org.itkk")).paths(PathSelectors.any())
        .build();
  }

  private ApiInfo apiInfo() {
    ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();
    apiInfoBuilder.title(this.projectName + " online api document");
    apiInfoBuilder.version(version);
    return apiInfoBuilder.build();
  }
```

###4.使用@Api来标记controller

``` java
@RestController
@RequestMapping("demo")
@Api(value = "demo", 
	consumes = "application/json", 
	produces = "application/json",
	protocols = "http")
public class DemoController {

}
```

###5.使用@ApiOperation来标记方法

``` java
  @ApiOperation(value = "add", notes = "add")
  @RequestMapping(value = "add", method = RequestMethod.GET)
  public RestResponse<Integer> add(Integer a, Integer b) {
    return new RestResponse<>(demoService.add(a, b));
  }
```

###6.使用@ApiImplicitParams和@ApiImplicitParam来标参数

``` java
  @ApiOperation(value = "add", notes = "add")
  @ApiImplicitParams({
      @ApiImplicitParam(paramType = "query", name = "a", value = "a", required = true,
          dataType = "int"),
      @ApiImplicitParam(paramType = "query", name = "b", value = "a", required = true,
          dataType = "int") })
  @RequestMapping(value = "add", method = RequestMethod.GET)
  public RestResponse<Integer> add(Integer a, Integer b) {
    return new RestResponse<>(demoService.add(a, b));
  }
```

###7.使用@ApiModel和@ApiModelProperty来标实体类

``` java
@ApiModel(description = "响应消息体")
public class RestResponse<T> implements Serializable {

  /**
   * 
   * 描述 : id
   * 
   */
  private static final long serialVersionUID = 1L;

  /**
   * 描述 : 响应ID
   */
  @ApiModelProperty(value = "响应ID", required = true, dataType = "string")
  private String id = UUID.randomUUID().toString();
 
  .............
  
}
```

## **代码仓库** (博客配套代码)

- [udf-starter : 基础项目,脚手架,框架](https://gitee.com/wangkang/udf)

- [udf-sample : 集成样例](https://gitee.com/wangkang/udf-sample)

##结束

以上配置结束之后,启动项目,访问`http://xxxxx/swagger-ui.html`即可能够访问接口文档,并且直接可以做接口调用测试.

然后对于Swagger2这个组件,目前看下来就是对业务代码有一定的入侵,总之使用前请根据自身项目情况做好评估,不要盲目跟风.

---------

想获得最快更新,请关注公众号

![想获得最快更新,请关注公众号](https://mmbiz.qlogo.cn/mmbiz_jpg/gjOvoY7GOt5a4dicfGbqze591YAEiaRONE0nOsiaur4nlsmKtUpRuONue28wJ9JfOXfBl99OoVmYncohMnEY4LMdg/0?wx_fmt=jpeg "想获得最快更新,请关注公众号")