柏乡县建设局网站站长工具官网查询
→ springboot 集成 Swagger2 ←
目录
- 1. 案例
- 2. info 配置
- 3. Docket 配置
- 1. 开关配置
- 2. 扫描路径
- 3. 路径匹配
- 4. 分组管理
- 4. 常用注解
- 1. 说明
- 2. 案例
1. 案例
这次直接使用 2.5.6 的 spring-boot 。
-
依赖：
<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> -
启动类加注解
@EnableOpenApi -
新建测试类
@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;} } -
访问 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
- 访问 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 {@Beanpublic Docket createDocket() {return new Docket(DocumentationType.OAS_30)// 指定 Swagger3 版本号.apiInfo(createApiInfo());}@Beanpublic 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<>());}
}
DocketSwagger 的实例，可通过 Docket 对象来配置 Swagger；ApiInfo文件描述的配置对象。
3. Docket 配置
1. 开关配置
@Beanpublic 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 {@Beanpublic Docket createDocket01() {return new Docket(DocumentationType.OAS_30)// 指定 Swagger3 版本号.groupName("other 组").enable(true)// 关闭文档.select().paths(PathSelectors.ant("/other/**")).build().apiInfo(createApiInfo());}@Beanpublic 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());}@Beanpublic 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;
}
