项目中Springboot整合Swagger2总结

     相信各位在公司写API文档数量应该不少，当然如果你还处在自己一个人开发前后台的年代，当我没说，如今为了前后台更好的对接，还是为了以后交接方便，都有要求写API文档。网上Springboot整合Swagger2的文章有很多，

手写Api文档的几个痛点：

1. 文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。
2. 接口返回结果不明确
3. 不能直接在线测试接口，通常需要使用工具，比如postman
4. 接口文档太多，不好管理

Swagger也就是为了解决这个问题，当然也不能说Swagger就一定是完美的，当然也有缺点，最明显的就是代码移入性比较强。

其他的不多说，想要了解Swagger的，可以去Swagger官网，可以直接使用Swagger editor编写接口文档，当然我们这里讲解的是SpringBoot整合Swagger2，直接生成接口文档的方式。

我就自己的项目进行总结，两种SwaggerUI样式的配置

配置一：

    1,pom.xml:    

•     <!-- Swagger2 增强版开始 -->
•         <dependency>
•             <groupId>io.springfox</groupId>
•             <artifactId>springfox-swagger2</artifactId>
•             <version>2.6.1</version>
•         </dependency>
•         <dependency>
•             <groupId>com.github.xiaoymin</groupId>
•             <artifactId>swagger-bootstrap-ui</artifactId>
•             <version>2.6.1</version>
•         </dependency>

1,SwaggerConfig配置

• @Configuration
• @EnableSwagger2
• public class SwaggerConfig {
•     @Bean
•     public Docket customDocket(){
•         ParameterBuilder ticketPar = new ParameterBuilder();
•         List<Parameter> pars = new ArrayList<Parameter>();
•         ticketPar.name("token").description("user token")
•                 .modelRef(new ModelRef("string")).parameterType("header")
•                 .required(false).build(); //header中的ticket参数非必填，传空也可以
•         pars.add(ticketPar.build());    //根据每个方法名也知道当前方法在设置什么参数
•  
•         return new Docket(DocumentationType.SWAGGER_2)
•                 .select()
•                 .apis(RequestHandlerSelectors.any())
•                 .build()
•                 .globalOperationParameters(pars)
•                 .apiInfo(apiInfo());
•     }
•     private ApiInfo apiInfo() {
•         return new ApiInfoBuilder()
•                 .title("ITS系统说明文档")
•                 .description("接口说明文档")
•                 .termsOfServiceUrl("")
•                 .contact(new Contact("ITS","xxx@foxmail.com","xxx@foxmail.com"))
•                 .version("1.0")
•                 .build();
•     }
• }

 

• 1，在controller接口上加
•   @ApiOperation(value = "test", notes = "\t 说明" + "\n\t 参数说明：" + "\n\t id - 主键 - 必填"）
• 1，在vo对象字段上加
• @ApiParam(name = "orderCode", value = "订单编号")
• 1，在返回实体字段上加
• @ApiModelProperty(name = "orderCode", value = "订单号")

   

 配置二：

• 2,pom.xml:    
• <dependency>
•     <groupId>io.springfox</groupId>
• <artifactId>springfox-swagger2</artifactId>
• <version>2.6.1</version>
• </dependency>
• <dependency>
• <groupId>io.springfox</groupId>
• <artifactId>springfox-swagger-ui</artifactId>
• <version>2.6.1</version>
• </dependency>

2,SwaggerConfig配置

• @Configuration
• @EnableSwagger2
• public class SwaggerConfig {
•    @Bean
•     public Docket createRestApi() {
•         return new Docket(DocumentationType.SWAGGER_2)
•                 .apiInfo(apiInfo())
•                 .select()
•                 .apis(RequestHandlerSelectors
•                         .basePackage("com.changjiu.its.components.controller")) // 配置需要扫描的包路径
•                 .paths(PathSelectors.any()).build();
•     }
•     private ApiInfo apiInfo() {
•         return new ApiInfoBuilder()
•                 .title("ITS系统说明文档")
•                 .description("接口说明文档")
•                 .termsOfServiceUrl("")
•                 .contact(new Contact("ITS","xxx@foxmail.com","xxx@foxmail.com"))
•                 .version("1.0")
•                 .build();
•     }
• }

2，在controller接口上加

•   @ApiOperation(value = "test", notes = "\t 说明" + "\n\t 参数说明："+ "\n\t id - 主键 - 必填"）
• 2，在vo对象字段上加
• @ApiParam(name = "orderCode", value = "订单编号")
• 2，在返回实体字段上加
• @ApiModelProperty(name = "orderCode", value = "订单号")