SpringBoot整合Swagger2

SpringBoot整合Swagger2

1. 添加maven依赖

   <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. 添加swagger2配置文件

   import org.springframework.context.annotation.Bean;
   import org.springframework.context.annotation.Configuration;
   import springfox.documentation.builders.ApiInfoBuilder;
   import springfox.documentation.builders.PathSelectors;
   import springfox.documentation.builders.RequestHandlerSelectors;
   import springfox.documentation.service.ApiInfo;
   import springfox.documentation.spi.DocumentationType;
   import springfox.documentation.spring.web.plugins.Docket;
   import springfox.documentation.swagger2.annotations.EnableSwagger2;
   
   @Configuration
   @EnableSwagger2
   public class Swagger2Config {
   
       @Bean
       public Docket createRestApi() {
           return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apiInfo())
                   .select()
                   // 扫描路径
                   .apis(RequestHandlerSelectors.basePackage("con.swagger.controller"))
                   .paths(PathSelectors.any())
                   .build();
       }
   
       private ApiInfo apiInfo() {
           return new ApiInfoBuilder()
                   .title("springboot利用swagger构建api文档")
                   .description("链接显示的文字")
                   .termsOfServiceUrl("网站链接")
                   .version("1.0")
                   .build();
       }
   
   }
   

3. 对接口增加描述

   import io.swagger.annotations.Api;
   import io.swagger.annotations.ApiModelProperty;
   import io.swagger.annotations.ApiOperation;
   import lombok.Getter;
   import lombok.Setter;
   import lombok.ToString;
   import org.springframework.web.bind.annotation.PostMapping;
   import org.springframework.web.bind.annotation.RestController;
   
   @Api(value = "SwaggerTestController")
   @RestController
   public class SwaggerTestController {
   
       @ApiOperation(value = "helloWord", notes = "链接", response = String.class)
       @PostMapping("/helloWord")
       public String helloWord(SwaggerModel swaggerModel){
           System.out.println(swaggerModel);
          return "helloWord";
       }
   }
   
   @Getter
   @Setter
   @ToString
   class SwaggerModel{
   
       @ApiModelProperty(value = "姓名")
       private String name;
   
       @ApiModelProperty(value = "年龄")
       private Integer age;
   }
   
   

4. 进入 http://localhost:8080/swagger-ui.html 页面查看接口信息

   

• 进入 http://localhost:8080/v2/api-docs 查看json信息

• 可用json信息来生产pdf文档，具体请移至 通过swagger2markup+asciidoctorj生成html和pdf文档并解决asciidoctorj生成的pdf文件中文显示不全问题（maven方式及java代码方式）

• 顺手记个问题

  1. 问题描述：访问http://localhost:8080/swagger-ui.html页面后台报错，但是不影响显示和使用

  2. 触发条件，在 Integer 字段上使用 @ApiModelProperty 注解，并不指定example的值，让其为默认（""），如图
     

3. 会导致 io.swagger.models.parameters.AbstractSerializableParameter 类的 getExample 方法报错
   
   我当前使用的版本进来这里的 this.example 为 null
   之前使用的某个版本进来 this.example 为 “”，则会走到 356行 return Long.valueOf(this.example);
   所以Long.valueOf(“”)报错