SpringBoot使用Swagger生成API文档

在多人协作的开发过程中，API文档不仅可以减少等待，也能保证开发的持续进行。有一些单元测试框架可以生成API文档，而Swagger可以在不写单元测试的情况下生成在线的API页面，并且可以直接在页面进行API调试。

1. 引入需要的依赖

        
            io.springfox
            springfox-swagger2
            2.6.1
        
        
            io.springfox
            springfox-swagger-ui
            2.6.1
        

2. 在启动类也就是XXXApplication类的同级目录下创建Swagger2类，作为配置类

@Configuration
@EnableSwagger2
public class Swagger2 {
      @Bean
      public Docket createRestApi() {
          return new Docket(DocumentationType.SWAGGER_2)
                  .apiInfo(apiInfo())
                  .select()
      .apis(RequestHandlerSelectors.basePackage("cn.com.wenyi.controller"))
                .paths(PathSelectors.any())
                .build();
    }

      private ApiInfo apiInfo() {
          return new ApiInfoBuilder()
                  .title("Brand Love APIS")
                  .description("基于指数数据的品牌趋势分析工具")
                  .version("1.0.3")
                  .build();
      }
}

通过@Configuration我们标记此类为配置类，会在SpringBoot项目启动的时候加载，@EnableSwagger2用来启动Swagger。
实际上我们已经完成了对Swagger的配置，Swagger会自动扫描我们配置的cn.com.wenyi.controller包下的接口自动生成接口文档。
其地址为：http://localhost:8080/swagger-ui.html

3.接下来我们可以对我们的接口参数进一步说明：

#在Controller上使用@Api会生成这个Controller的整体描述
@Api(value = "Base Index API", description = "基础指数数据")

#在具体方法上使用@ApiOperation可以生成接口的描述
@ApiOperation(value = "回溯数据", notes = "回溯品牌历史指数数据")

#在方法上使用@ApiImplicitParam可以增加对参数等的描述
@ApiImplicitParam(name = "brand", value = "品牌名称", required = true, dataType = "String", paramType = "query")

其他更多操作我们可以查看网上的文章晚上我们的接口文档。

结果示例

总结

Swagger生成的文档在我看来并不精美，但是对于多人协作开发来说的确是方便了很多。
其次Swagger可以直接在页面进行请求操作大大减少了需要使用额外工具来模拟请求的开销。
并且是由开发者直接维护请求参数等，避免模拟请求传错参数造成额外没必要的沟通。

最后Swagger在我看来最大的弊端除了不够精美以外，就是浸入式的写法会造成代码臃肿，且在移除时，需要删除大量代码。而这种做法显得有些不优雅。