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

Posted 我要睡觉了∑

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了Swagger认识与使用 Swagger 实现接口文档相关的知识,希望对你有一定的参考价值。

文章目录

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 注解中,指定一个请求参数的各个方面 |

以上是关于Swagger认识与使用 Swagger 实现接口文档的主要内容,如果未能解决你的问题,请参考以下文章

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

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

Swagger ,Knife4J 项目接口文档与 Postman 进行集成,实现接口的快速导入

Swagger ,Knife4J 项目接口文档与 Postman 进行集成,实现接口的快速导入

SpringBoot集成swagger 注解使用步骤

SpringBoot集成swagger 注解使用步骤