十八、接口管理
1、Swager
使用Swagger你只需要按照它的规范去定义接口及接口相关的信息，就可以做到生成接口文档，以及在线接口调试页面。
官网: https://swagger.io/
Knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案。
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>4.4.0</version></dependency>
-
导入knife4j的maven坐标
-
在配置类中加入knife4j相关配置
import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;@Configuration
public class WebMvcConfiguration extends WebMvcConfigurationSupport{/*
*
* 在配置类中加入knife4j相关配置*/
@Bean
public OpenAPI springShopOpenAPI() {log.info("knife4j配置成功");return new OpenAPI()// 接口文档标题.info(new Info().title("永恒之月")// 接口文档简介.description("接口管理")// 接口文档版本.version("v1.0")// 开发者联系方式.contact(new Contact().name("yhzy").email("yhzyai@163.com"))).externalDocs(new ExternalDocumentation().description("SpringBoot基础框架").url("http://127.0.0.1:9091"));
}// 下面是分组@Beanpublic GroupedOpenApi groupedOpenApi01(){return GroupedOpenApi.builder().group("管理端接口")// 该分组所在的包.packagesToScan("fun.yhzy.controller.admin").build();}@Beanpublic GroupedOpenApi groupedOpenApi02(){return GroupedOpenApi.builder().group("用户端接口")// 该分组所在的包.packagesToScan("fun.yhzy.controller.user").build();}/*** 设置静态资源映射,拦截器放行资源* @param registry*/protected void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");}}
- yml配置
#knife4j 相关配置
springdoc:swagger-ui:path: /swagger-ui.htmltags-sorter: alphaoperations-sorter: alphaapi-docs:path: /v3/api-docs# knife4j的增强配置，不需要增强可以不配
knife4j:enable: truesetting:language: zh_cn#是否开启密码保护basic:enable: trueusername: rootpassword: 123
1.2 Swager 常用注解
通过注解可以控制生成的接口文档，使接口文档拥有更好的可读性，常用注解如下:
| 注解 | 说明 |
|---|---|
| @Tag | 作用于控制类上，name属性用于描述控制类 |
| @Operation | 作用于控制类的方法上面，summary属性用于描述方法 |
| @Parameter(hidden = true) 、@Operation(hidden = true)、@Hidden | 这是用于排除或隐藏api |
| @Schema | DTO实体属性，name属性用于描述属性 |
创建好后直接访问：后端地址:端口号/doc.html，如：http://localhost:9091/doc.html