SpringBoot整合Swagger2

一时失言乱红尘 2024-04-18 14:51 8阅读 0赞

# 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 页面查看接口信息**
    
    ![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI1MjE1ODIx_size_16_color_FFFFFF_t_70]

*  进入 http://localhost:8080/v2/api-docs 查看json信息
 *  可用json信息来生产pdf文档，具体请移至 [通过swagger2markup+asciidoctorj生成html和pdf文档并解决asciidoctorj生成的pdf文件中文显示不全问题（maven方式及java代码方式）][swagger2markup_asciidoctorj_html_pdf_asciidoctorj_pdf_maven_java]
 *  **顺手记个问题**
    
    1.  问题描述：访问http://localhost:8080/swagger-ui.html页面后台报错，但是不影响显示和使用
    2.  触发条件，在 Integer 字段上使用 @ApiModelProperty 注解，并不指定example的值，让其为默认（""），如图  
        ![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI1MjE1ODIx_size_16_color_FFFFFF_t_70 1]

1.  会导致 io.swagger.models.parameters.AbstractSerializableParameter 类的 getExample 方法报错  
    ![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI1MjE1ODIx_size_16_color_FFFFFF_t_70 2]  
    我当前使用的版本进来这里的 this.example 为 null  
    之前使用的某个版本进来 this.example 为 “”，则会走到 356行 return Long.valueOf(this.example);  
    所以Long.valueOf(“”)报错

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI1MjE1ODIx_size_16_color_FFFFFF_t_70]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/18/1639640ecf324fae810152690467079e.png
[swagger2markup_asciidoctorj_html_pdf_asciidoctorj_pdf_maven_java]: https://blog.csdn.net/qq_25215821/article/details/79175535
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI1MjE1ODIx_size_16_color_FFFFFF_t_70 1]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/18/0af62b5c60914428ac76e9ec021c57ed.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI1MjE1ODIx_size_16_color_FFFFFF_t_70 2]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/18/40f4cf9e974c4552a1397e32834f4517.png