→ springboot 集成 Swagger2 ←

目录

• 1. 案例
• 2. info 配置
• 3. Docket 配置
• • 1. 开关配置
  • 2. 扫描路径
  • 3. 路径匹配
  • 4. 分组管理
  • 4. 常用注解
  • • 1. 说明
    • 2. 案例

      1. 案例

      这次直接使用 2.5.6 的 spring-boot 。

      1. 依赖：

             
                 org.springframework.boot
                 spring-boot-starter-parent
                 2.5.6
                  
             
             
                 
                     org.springframework.boot
                     spring-boot-starter-web
                 
                 
                 
                     io.springfox
                     springfox-boot-starter
                     3.0.0
                 
                 
                 
                     org.projectlombok
                     lombok
                     true
                 
             
         

      2. 启动类加注解 @EnableOpenApi

      3. 新建测试类

         @RestController
         @RequestMapping("/test")
         public class SwaggerController {
             @GetMapping("/get")
             public String getStr(String str) {
                 return "SELECT " + str;
             }
             @PostMapping("/post")
             public String postStr(String str) {
                 return "CREATE " + str;
             }
             @PutMapping("/put")
             public String putStr(String str) {
                 return "UPDATE " + str;
             }
             @NoSwagger
             @PatchMapping("/patch")
             public String patchStr(String str) {
                 return "UPDATE " + str;
             }
             @DeleteMapping("/delete")
             public String deleteStr(String str) {
                 return "DELETE " + str;
             }
         }
         

      4. 访问 http://127.0.0.1:8080/swagger-ui.html ，没错，又是 Error 页面

         

      此部分参考：https://blog.csdn.net/mmmm0584/article/details/117786055

      ---

      在swagger3.0中，swagger-ui.html的位置发生了变化：

        →  

      所以路径也变了：http://127.0.0.1:8080/swagger-ui.html → http://127.0.0.1:8080/swagger-ui/index.html

      5. 访问 http://127.0.0.1:8080/swagger-ui/index.html

         

      2. info 配置

      新建一个配置类：

      import org.springframework.context.annotation.Bean;
      import org.springframework.context.annotation.Configuration;
      import springfox.documentation.builders.ApiInfoBuilder;
      import springfox.documentation.service.ApiInfo;
      import springfox.documentation.service.Contact;
      import springfox.documentation.service.VendorExtension;
      import springfox.documentation.spi.DocumentationType;
      import springfox.documentation.spring.web.plugins.Docket;
      import java.util.HashSet;
      @Configuration
      public class Swagger3Conf {
          @Bean
          public Docket createDocket() {
              return new Docket(DocumentationType.OAS_30)// 指定 Swagger3 版本号
                      .apiInfo(createApiInfo());
          }
          @Bean
          public ApiInfo createApiInfo() {
      //        // 写法一
      //        return new ApiInfoBuilder()
      //                .title("Swagger3 文档案例")
      //                .description("Swagger ：一套围绕 Open API 规范构建的一款 RESTful 接口的文档在线自动生成和功能测试 API 。")
      //                .version("1.0.1")
      //                .contact(
      //                        // name url email
      //                        new Contact("364.99°的文档", // 文档发布者名称
      //                                "https://blog.csdn.net/m0_54355172", // 文档发布者的网站地址
      //                                "2190826197@qq.com" // 文档发布者的邮箱
      //                        )
      //                )
      //                .build();
              // 写法二
              return new ApiInfo(
                      "Swagger3 文档案例",
                      "Swagger ：一套围绕 Open API 规范构建的一款 RESTful 接口的文档在线自动生成和功能测试 API 。",
                      "1.0.1",
                      "https://blog.csdn.net/m0_54355172",
                      new Contact("364.99°的文档", // 文档发布者名称
                                      "https://blog.csdn.net/m0_54355172", // 文档发布者的网站地址
                                      "2190826197@qq.com" // 文档发布者的邮箱
                              ),
                      "364.99°",
                      "https://blog.csdn.net/m0_54355172",
                      new HashSet<>());
              }
      }
      

      

      • Docket Swagger 的实例，可通过 Docket 对象来配置 Swagger；
      • ApiInfo 文件描述的配置对象。

        3. Docket 配置

        1. 开关配置

            @Bean
            public Docket createDocket() {
                return new Docket(DocumentationType.OAS_30)// 指定 Swagger3 版本号
                        .enable(false)// 关闭文档
                        .apiInfo(createApiInfo());
            }
        

        

        注意： 一般只有在测试环境才会用到 Swagger，在生产环境中会把它关闭掉，为了安全与效率。

        2. 扫描路径

                        .select()
                        .apis(RequestHandlerSelectors.basePackage("com.chenjy.swagger2.controller"))
                        .build()
        

        

        3. 路径匹配

        新建一个控制器：

        @Api(tags = "other 接口 API")
        @RestController
        @RequestMapping("/other")
        public class OtherController {
            @GetMapping("getInfo")
            public String getInfo() {
                return "information";
            }
        }
        

                        .select()
                        .paths(PathSelectors.ant("/other/**"))
                        .build()
        

        

        4. 分组管理

        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.service.Contact;
        import springfox.documentation.spi.DocumentationType;
        import springfox.documentation.spring.web.plugins.Docket;
        import java.util.HashSet;
        @Configuration
        public class Swagger3Conf {
            @Bean
            public Docket createDocket01() {
                return new Docket(DocumentationType.OAS_30)// 指定 Swagger3 版本号
                        .groupName("other 组")
                        .enable(true)// 关闭文档
                        .select()
                        .paths(PathSelectors.ant("/other/**"))
                        .build()
                        .apiInfo(createApiInfo());
            }
        	@Bean
            public Docket createDocket02() {
                return new Docket(DocumentationType.OAS_30)
                        .groupName("test 组")
                        .select()
                        .apis(RequestHandlerSelectors.basePackage("com.chenjy.swagger2.controller"))
                        .build()
                        .apiInfo(
                                new ApiInfoBuilder()
                                        .title("Swagger3 文档案例")
                                        .build()
                        );
            }
            @Bean
            public ApiInfo createApiInfo() {
        //        // 写法一
        //        return new ApiInfoBuilder()
        //                .title("Swagger3 文档案例")
        //                .description("Swagger ：一套围绕 Open API 规范构建的一款 RESTful 接口的文档在线自动生成和功能测试 API 。")
        //                .version("1.0.1")
        //                .contact(
        //                        // name url email
        //                        new Contact("364.99°的文档", // 文档发布者名称
        //                                "https://blog.csdn.net/m0_54355172", // 文档发布者的网站地址
        //                                "2190826197@qq.com" // 文档发布者的邮箱
        //                        )
        //                )
        //                .build();
                // 写法二
                return new ApiInfo(
                        "Swagger3 文档案例",
                        "Swagger ：一套围绕 Open API 规范构建的一款 RESTful 接口的文档在线自动生成和功能测试 API 。",
                        "1.0.1",
                        "https://blog.csdn.net/m0_54355172",
                        new Contact("364.99°的文档", // 文档发布者名称
                                        "https://blog.csdn.net/m0_54355172", // 文档发布者的网站地址
                                        "2190826197@qq.com" // 文档发布者的邮箱
                                ),
                        "364.99°",
                        "https://blog.csdn.net/m0_54355172",
                        new HashSet<>());
                }
        }
        

        

        4. 常用注解

        1. 说明

        和 Swagger2 一样，其常用注解还是如下几个：

        常用注解	注解说明	常用属性	属性说明
        @Api	类注解，常用来给文档中的控制器取别名	tags	别名
        @ApiOperation	方法/类注解，常用来描述方法	value notes	方法说明 方法备注
        @ApiParam	参数/方法/属性注解，常用来描述参数	name value required	参数名 补充描述 是否必须
        @ApiIgnore	方法/属性注解，使被标注方法不生成文档	-	-
        @ApiImplicitParam	方法注解，描述一个参数	name value name required paramType dataType defaultValue	参数名 补充说明 是否必传 参数位置（header、query、path） 参数类型（默认 String） 默认值
        @ApiImplicitParams	搭配 @ApiImplicitParam 一起使用，描述一组参数
        @ApiResponse	方法注解，表达一个错误的响应信息	code message response	整型 字符串 异常信息（默认 String 类型）
        @ApiResponses	搭配 @ApiResponse 一起使用，参考 @ApiImplicitParams
        @ApiModel	类注解，当此实体类被作为返回类型用于 API 帮助文档中的接口方法中，此注解被解析	value description	实体类名 补充描述
        @ApiModelProperty	属性注解，搭配 @ApiModel 使用	value example hidden	属性名 示例 是否隐藏

        2. 案例

        import com.chenjy.swagger2.dto.TestDto;
        import io.swagger.annotations.*;
        import org.springframework.web.bind.annotation.*;
        import springfox.documentation.annotations.ApiIgnore;
        @Api(tags = {"test 接口 API"})
        @RestController
        public class SwaggerController {
            @ApiResponses({
                    @ApiResponse(code = 1, message = "查询成功"),
                    @ApiResponse(code = -1, message = "查询失败")
            })
            @ApiImplicitParams({
                    @ApiImplicitParam(name = "name", value = "角色名", required = false, defaultValue = "张三"),
                    @ApiImplicitParam(name = "num", value = "序列号", required = true)
            }
            )
            @PostMapping("/getInfo")
            public TestDto getInfo(String name, Integer num) {
                return new TestDto(name, num);
            }
            
            @ApiIgnore
            @GetMapping("/getStr")
            public String getStr(String name) {
                return name;
            }
        }
        

        import io.swagger.annotations.ApiModel;
        import io.swagger.annotations.ApiModelProperty;
        import lombok.AllArgsConstructor;
        import lombok.Data;
        import lombok.NoArgsConstructor;
        @Data
        @NoArgsConstructor
        @AllArgsConstructor
        @ApiModel( value = "角色实体类", description = "存储数据并返回")
        public class TestDto {
            @ApiModelProperty( value = "姓名", example = "张三", hidden = false)
            private String name;
            @ApiModelProperty( value = "序列号", example = "1")
            private Integer num;
        }
        

         
         一个完整的网站制作需要哪些部分组成  中小企业发展促进中心  购物网站建设  免费网站建设seo  广告公司网站制作  seo网络推广优势