【Swagger】认识与使用 Swagger 实现接口文档

灰太狼 2024-04-03 11:33 69阅读 0赞

#### 文章目录 ####

*  1. 介绍
 *  2. 使用方式
 *  3. 常用注解

## 1. 介绍 ##

使用 Swagger 你只需要按照它的规范去定义接口及接口相关的信息，再通过 Swagger 衍生出来的一系列项目和工具，就可以做到生成各种各式的接口文档，以及在线接口调试页面等等。

> Swagger 官网：https://swagger.io/

由于直接使用 Swagger 操作是比较繁琐的，因此可以使用一些基于 Swagger 实现的框架，例如 knife4j，它是一个为 Java MVC 框架集成 Swagger 生成 Api 文档的增强解决方案。

## 2. 使用方式 ##

1.  导入 knife4j 的 maven 坐标
    
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>3.0.3</version>
        </dependency>
2.  导入 knife4j 的相关配置类（WebMvcConfig）
    
        @Configuration
        @EnableSwagger2 // 开启 Swagger 文档的功能
        @EnableKnife4j
        public class WebMvcConfig extends WebMvcConfigurationSupport {
              
        
            @Bean
            public Docket createRestApi(){
              
                // 文档类型
                return new Docket(DocumentationType.SWAGGER_2)
                        .apiInfo(apiInfo())
                        .select()
                        .apis(RequestHandlerSelectors.basePackage("com.dmw.demo.controller"))	// 项目中 controller 的包路径
                        .paths(PathSelectors.any())
                        .build();
            }
            
            private ApiInfo apiInfo(){
              
                return new ApiInfoBuilder()
                        .title("项目名称")
                        .version("项目版本")
                        .description("项目描述")
                        .build();
            }
        }
3.  设置静态资源映射（WebMvcConfig 类中的 addResourceHandlers 方法），否则接口文档页面无法访问
    
        @Override
        protected void addResourceHandlers(ResourceHandlerRegistry registry) {
              
            
            registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
            registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
            
        }
4.  如果希望不登陆就能够访问接口文档，那么要在拦截器或者过滤器中放行以下请求路径：
    
        "/doc.html",
        "/webjars/**",
        "/swagger-resources",
        "/v2/api-docs"
5.  项目启动后通过访问 `ip:端口号/doc.html` 就能够看到接口文档的信息 \[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-yVDG9QH8-1665503782253)(C:/Users/bbbbbge/Pictures/接单/1665423831678.png)\]

## 3. 常用注解 ##

<table> 
 <thead> 
  <tr> 
   <th>注解</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><code>@Api</code></td> 
   <td>用在请求的类上，例如 Controller，表示对类的说明</td> 
  </tr> 
  <tr> 
   <td><code>@ApiModel</code></td> 
   <td>用在类上，通常是实体类，表示一个返回响应数据的信息</td> 
  </tr> 
  <tr> 
   <td><code>@ApiModelProperty</code></td> 
   <td>用在属性上，描述响应类的属性</td> 
  </tr> 
  <tr> 
   <td><code>@ApiOperation</code></td> 
   <td>用在请求的方法上，说明方法的用途</td> 
  </tr> 
  <tr> 
   <td><code>@ApiImplicitParams</code></td> 
   <td>用在请求的方法上，表示一组参数说明</td> 
  </tr> 
  <tr> 
   <td><code>@ApiImplicitParam</code></td> 
   <td>用在 @ApiImplicitParams 注解中，指定一个请求参数的各个方面</td> 
  </tr> 
 </tbody> 
</table>

| `@ApiImplicitParam` | 用在 @ApiImplicitParams 注解中，指定一个请求参数的各个方面 |