Swagger3快速使用

x33g5p2x  于2021-10-25 转载在 其他  
字(3.3k)|赞(0)|评价(0)|浏览(431)

参看

https://swagger.io/
https://springdoc.org/

https://www.bilibili.com/video/BV1F44y1t7aK

http://itboyhub.com/2021/01/29/springboot-swagger3

Swagger 为我们提供了一套通过代码和注解自动生成文档的方法,这一点对于保证API 文档的及时性将有很大的帮助。

swagger3支持OpenAPI,发布于2020年7月。它的很多使用细节与swagger2中一致,这里就不做出多的解释【点击我,快速学习swagger2】。

swagger3对于swagger2的优势:

  • 支持OpenAPI。
  • 无需配置,即可开启。

一、快速使用

对于swagger2来说,需要引入依赖有:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

一个用来生成接口文档(JSON 数据),另一个用来展示将 JSON 可视化。

而在swagger3中,使用一个starter就解决了

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

和 Spring Boot 中的其他 starter 一样,springfox-boot-starter 依赖可以实现零配置以及自动配置支持。即如果没有其他特殊需求,加一个这个依赖,接口文档就自动生成了。

启动项目之后,访问http://localhost:8080/swagger-ui/index.html进入测试接口页面(访问接口自设)。

二、增加配置类

这是使用swagger的核心,对于 开关、分组和过滤 等信息的配置,都是在config类中进行配置。

1.application

server:
  port: 8082

config:
  swagger3:
    flag: true

2.Swagger3Config

在Swagger中添加JWT认证,点击我跳转

package com.pdh.file.config;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.ArrayList;

/** * @Author: 彭_德华 * @Date: 2021-10-14 14:57 * 覆盖默认的配置信息 */
@Configuration
@EnableOpenApi
public class Swagger3Config {

    @Value("${config.swagger3.flag}") //读取配置文件
    private boolean flag;

    @Bean
    public Docket docket(Environment environment){
        return new Docket(DocumentationType.OAS_30) // 指定3.0版本
                .groupName("文件上传")
                .apiInfo(apiInfo())
                .enable(flag)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.pdh.file.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){

        return new ApiInfo("基于SpringBoot上传文件",
                "基于SpringBoot,实现上传文件到本地电脑和上传文件到云服务器(以七牛云服务器为例)",
                "v1.0",
                "https://blog.csdn.net/yeahPeng11",
                new Contact("彭德华","https://blog.csdn.net/yeahPeng11","pdhcool@163.com"),
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

配置类的写法和作用,可参考并查看swagger2。

三、接口的地址

3.0 中的接口地址也和之前有所不同,以前在 2.9.2 中我们主要访问两个地址:

  • 文档接口地址:http://localhost:8080/v2/api-docs
  • 文档页面地址:http://localhost:8080/swagger-ui.html

现在在 3.0 中,这两个地址也发生了变化:

  • 文档接口地址:http://localhost:8080/v3/api-docs
  • 文档页面地址:http://localhost:8080/swagger-ui/index.html

特别是文档页面地址,如果用了 3.0,而去访问之前的页面,会报 404。

访问截图:

四、注解

支持swagger2的所有注解,并且在 3.0 中还提供了一些其他注解。例如使用:

  • @EnableOpenApi 代替以前旧版本中的 @EnableSwagger2。
  • @ApiOperation 代替以前旧版本中的 @Operation。

常用注解

这几个注解使用起来都是非常的简单,可结合源码使用(源码一看就懂)

  • @Api:用在controller类,描述API接口
  • @ApiOperation:描述接口方法
  • @ApiModel:描述对象
  • @ApiModelProperty:描述对象属性
  • @ApiImplicitParams:描述接口参数
  • @ApiResponses:描述接口响应
  • @ApiIgnore:忽略接口方法

相关文章