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

Posted 2023-02-04 吞吞吐吐大魔王

文章目录

• 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. 常用注解

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

           |

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