springboot 集成 Swagger3（速通）

→ springboot 集成 Swagger2 ←

目录

1. 案例

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

1. 依赖：<parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>2.5.6</version><relativePath/><!-- lookup parent from repository --></parent><dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><!--swagger3--><dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>3.0.0</version></dependency><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><optional>true</optional></dependency></dependencies>
2. 启动类加注解 @EnableOpenApi
3. 新建测试类@RestController@RequestMapping("/test")publicclassSwaggerController{@GetMapping("/get")publicStringgetStr(String str){return"SELECT "+ str;}@PostMapping("/post")publicStringpostStr(String str){return"CREATE "+ str;}@PutMapping("/put")publicStringputStr(String str){return"UPDATE "+ str;}@NoSwagger@PatchMapping("/patch")publicStringpatchStr(String str){return"UPDATE "+ str;}@DeleteMapping("/delete")publicStringdeleteStr(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

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

2. info 配置

新建一个配置类：

importorg.springframework.context.annotation.Bean;importorg.springframework.context.annotation.Configuration;importspringfox.documentation.builders.ApiInfoBuilder;importspringfox.documentation.service.ApiInfo;importspringfox.documentation.service.Contact;importspringfox.documentation.service.VendorExtension;importspringfox.documentation.spi.DocumentationType;importspringfox.documentation.spring.web.plugins.Docket;importjava.util.HashSet;@ConfigurationpublicclassSwagger3Conf{@BeanpublicDocketcreateDocket(){returnnewDocket(DocumentationType.OAS_30)// 指定 Swagger3 版本号.apiInfo(createApiInfo());}@BeanpublicApiInfocreateApiInfo(){//        // 写法一//        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", // 文档发布者的网站地址//                                "[email protected]" // 文档发布者的邮箱//                        )//                )//                .build();// 写法二returnnewApiInfo("Swagger3 文档案例","Swagger ：一套围绕 Open API 规范构建的一款 RESTful 接口的文档在线自动生成和功能测试 API 。","1.0.1","https://blog.csdn.net/m0_54355172",newContact("364.99°的文档",// 文档发布者名称"https://blog.csdn.net/m0_54355172",// 文档发布者的网站地址"[email protected]"// 文档发布者的邮箱),"364.99°","https://blog.csdn.net/m0_54355172",newHashSet<>());}}

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

3. Docket 配置

1. 开关配置

@BeanpublicDocketcreateDocket(){returnnewDocket(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")publicclassOtherController{@GetMapping("getInfo")publicStringgetInfo(){return"information";}}

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

4. 分组管理

importorg.springframework.context.annotation.Bean;importorg.springframework.context.annotation.Configuration;importspringfox.documentation.builders.ApiInfoBuilder;importspringfox.documentation.builders.PathSelectors;importspringfox.documentation.builders.RequestHandlerSelectors;importspringfox.documentation.service.ApiInfo;importspringfox.documentation.service.Contact;importspringfox.documentation.spi.DocumentationType;importspringfox.documentation.spring.web.plugins.Docket;importjava.util.HashSet;@ConfigurationpublicclassSwagger3Conf{@BeanpublicDocketcreateDocket01(){returnnewDocket(DocumentationType.OAS_30)// 指定 Swagger3 版本号.groupName("other 组").enable(true)// 关闭文档.select().paths(PathSelectors.ant("/other/**")).build().apiInfo(createApiInfo());}@BeanpublicDocketcreateDocket02(){returnnewDocket(DocumentationType.OAS_30).groupName("test 组").select().apis(RequestHandlerSelectors.basePackage("com.chenjy.swagger2.controller")).build().apiInfo(newApiInfoBuilder().title("Swagger3 文档案例").build());}@BeanpublicApiInfocreateApiInfo(){//        // 写法一//        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", // 文档发布者的网站地址//                                "[email protected]" // 文档发布者的邮箱//                        )//                )//                .build();// 写法二returnnewApiInfo("Swagger3 文档案例","Swagger ：一套围绕 Open API 规范构建的一款 RESTful 接口的文档在线自动生成和功能测试 API 。","1.0.1","https://blog.csdn.net/m0_54355172",newContact("364.99°的文档",// 文档发布者名称"https://blog.csdn.net/m0_54355172",// 文档发布者的网站地址"[email protected]"// 文档发布者的邮箱),"364.99°","https://blog.csdn.net/m0_54355172",newHashSet<>());}}

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. 案例

importcom.chenjy.swagger2.dto.TestDto;importio.swagger.annotations.*;importorg.springframework.web.bind.annotation.*;importspringfox.documentation.annotations.ApiIgnore;@Api(tags ={"test 接口 API"})@RestControllerpublicclassSwaggerController{@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")publicTestDtogetInfo(String name,Integer num){returnnewTestDto(name, num);}@ApiIgnore@GetMapping("/getStr")publicStringgetStr(String name){return name;}}

importio.swagger.annotations.ApiModel;importio.swagger.annotations.ApiModelProperty;importlombok.AllArgsConstructor;importlombok.Data;importlombok.NoArgsConstructor;@Data@NoArgsConstructor@AllArgsConstructor@ApiModel( value ="角色实体类", description ="存储数据并返回")publicclassTestDto{@ApiModelProperty( value ="姓名", example ="张三", hidden =false)privateString name;@ApiModelProperty( value ="序列号", example ="1")privateInteger num;}