Swagger
快来分享你的内容吧～
2024-10-28·@编程小助手 微信: leikooo_
Knife4j 接口文档
什么是接口文档？写接口信息的文档。 每个接口的信息包括： * 请求参数 * 响应参数 * 错误码 * 接口地址 * 接口名称 * 请求类型 * 请求格式 * 备注 谁用接口文档？ 答：一般是后端或者负责人来提供，后端和前端都要使用。 为什么需要接口文档？ ●有个书面内容（背书或者归档），便于大家参考和查阅，便于 沉淀和维护 ，拒绝口口相传 ●接口文档便于前端和后端开发对接，前后端联调的 介质 。后端 => 接口文档 <= 前端 ●好的接口文档支持在线调试、在线测试，可以作为工具提高我们的开发测试效率 怎么做接口文档？ ●手写：比如腾讯文档、Markdown 笔记 ●自动化接口文档生成：自动根据项目代码生成完整的文档或在线调试的网页。Swagger、Postman（侧重接口管理）（国外）；apifox、apipost、eolink（国产） 使用的 SpringBoot 版本是： 2.7.13 使用的 Knife4j 版本是：https://doc.xiaominfo.com/v2/documentation/get\_start.html 对应的 pom 文件 ```plaintext <!-- Swagger--> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <version>2.0.7</version> </dependency> ``` 如果如果 springboot version >= 2.6，需要添加如下配置： ```yml spring: mvc: pathmatch: matching-strategy: ANT_PATH_MATCHER ``` 访问的地址是：http://localhost:端口/doc.htm ```java /** * knife4j 配置类，集成了 swagger */ @Configuration @EnableSwagger2WebMvc public class Knife4jConfiguration { @Bean public Docket defaultApi2() { Docket docket=new Docket(DocumentationType.SWAGGER_2) .apiInfo(new ApiInfoBuilder() //.title("swagger-bootstrap-ui-demo RESTful APIs") .description("用户匹配系统") .termsOfServiceUrl("https://github.com/lieeew") .contact("xx@qq.com") .version("1.0") .build()) //分组名称 .groupName("2.0版本") .select() //这里指定Controller扫描包路径 .apis(RequestHandlerSelectors.basePackage("com.yupi.user_center.controller")) .paths(PathSelectors.any()) .build(); return docket; } } ```
Swagger的使用方式、常用注解
### 一、介绍 使用Swagger你只需要按照它的规范去定义接口及接口相关的信息，再通过Swagger衍生出来的一系列项目和工具就可以做到生成各种格式的接口文档，以及在线接口调试页面等等.官网: [https://swagger.io/](https://swagger.io/) knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案。 `<dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <version>3.0.2</version> </dependency>` ### 二、使用方式 **操作步骤** 1、导入knife4j的maven坐标 在项目的`pom.xml`文件中添加以下依赖坐标： `<dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <version>2.0.9</version> </dependency>` 2、导入knife4j相关配置类: 在Spring Boot的配置文件（如application.yml或application.properties）中添加以下配置项： `knife4j: swagger-ui: enabled: true # 是否启用Swagger-UI，默认为true title: API文档 # 文档标题 description: 接口文档 # 文档描述` 3、设置静态资源，否则接口文档页面无法访问 为了能够访问到Swagger生成的接口文档页面，需要配置静态资源映射。示例代码如下： `@Configuration public class WebMvcConfig implements WebMvcConfigurer { @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("doc.html") .addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**") .addResourceLocations("classpath:/META-INF/resources/webjars/"); } }` 4、在过滤器Filter中设置不需要处理的请求路径 有时候，我们可能需要设置一些不需要被Swagger处理的请求路径。这可以通过自定义Filter来实现。示例代码如下： `@Component public class SwaggerFilter implements Filter { @Override public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain filterChain) throws IOException, ServletException { HttpServletRequest request = (HttpServletRequest) servletRequest; if (request.getRequestURI().startsWith("/exclude")) { // 不处理的请求路径，直接放行 filterChain.doFilter(servletRequest, servletResponse); } else { // 其他请求路径由Swagger处理 // ... } } // ... }` ### 3、Swagger常用注解 注解 说明 @Api 用在请求的类上，例如Controller，表示对类的说明 @ApiModel 用在类上，通常是实体类，表示一个返回响应数据的信息 @ApiModelProperty 用在属性上，描述响应类的属性 @ApiOperation 用在请求的方法上，说明方法的用途、作用 @ApilmplicitParams 用在请求的方法上，表示一组参数说明 @ApilmplicitParam 用在@ApilmplicitParams注解中，指定一个请求参数的各个方面