Swagger3配置

时间:2025-03-18 14:20:34

swagger介绍

Swagger 是一套基于 OpenAPI 规范(OpenAPI Specification,OAS)构建的开源工具,可以帮助我们设计、构建、记录以及使用 Rest API。

OAS本身是一个API规范,它用于描述一整套API接口,包括一个接口是哪种请求方式、哪些参数、哪些header等,都会被包括在这个文件中。它在设计的时候通常是YAML格式,这种格式书写起来比较方便,而在网络中传输时又会以json形式居多,因为json的通用性比较强。

Swagger 主要包含了以下三个部分:

  • Swagger Editor:基于浏览器的编辑器,我们可以使用它编写我们 OpenAPI 规范。
  • Swagger UI:它会将我们编写的 OpenAPI 规范呈现为交互式的 API 文档,后文我将使用浏览器来查看并且操作我们的 Rest API。
  • Swagger Codegen:它可以通过为 OpenAPI(以前称为 Swagger)规范定义的任何 API 生成服务器存根和客户端 SDK 来简化构建过程。

springfox介绍

由于Spring的流行,Marty Pitt编写了一个基于Spring的组件swagger-springmvc,用于将swagger集成到springmvc中来,而springfox则是从这个组件发展而来。

通常SpringBoot项目整合swagger需要用到两个依赖:springfox-swagger2和springfox-swagger-ui,用于自动生成swagger文档。

springfox-swagger2:这个组件的功能用于帮助我们自动生成描述API的json文件 springfox-swagger-ui:就是将描述API的json文件解析出来,用一种更友好的方式呈现出来。

SpringFox 3.0.0 发布

官方说明:

SpringFox 3.0.0 发布了,SpringFox 的前身是 swagger-springmvc,是一个开源的 API doc 框架,可以将 Controller 的方法以文档的形式展现。

首先,非常感谢社区让我有动力参与这个项目。在这个版本中,在代码、注释、bug报告方面有一些非常惊人的贡献,看到人们在问题论坛上跳槽来解决问题,我感到很谦卑。它确实激励我克服“困难”,开始认真地工作。有什么更好的办法来摆脱科维德的忧郁!

注意:这是一个突破性的变更版本,我们已经尽可能地保持与springfox早期版本的向后兼容性。在2.9之前被弃用的api已经被积极地删除,并且标记了将在不久的将来消失的新api。所以请注意这些,并报告任何遗漏的内容。

基本配置

import ;
import ;
import ;
import ;
import ;
import ;
import ;
import ;
import ;
import ;

import ;
import ;

/**
 * swagger访问地址
 * http://localhost:8080/swagger-ui/
 * 一些常用注解说明
 * @Api:用在controller类,描述API接口
 * @ApiOperation:描述接口方法
 * @ApiModel:描述对象
 * @ApiModelProperty:描述对象属性
 * @ApiImplicitParams:描述接口参数
 * @ApiResponses:描述接口响应
 * @ApiIgnore:忽略接口方法
 */
@RequiredArgsConstructor
@EnableOpenApi
@Configuration
public class Swagger3Config {

    private final SwaggerProperties swaggerProperties;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)     //文档版本
                .pathMapping("/")
                .enable(())  //是否开启swagger
                .apiInfo(apiInfo())                     //将api的元信息设置为包含在json ResourceListing响应中。
                .select()                               //选择哪些接口作为swagger的doc发布
                .apis(())
                .paths(())
                .build()
                .protocols(new HashSet<>(("http", "https")))   //支持的通讯协议集合
                ;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(())
                .description(())
                .version(())
                .build();
    }

}
import ;
import ;
import ;

@Data
@Component
@ConfigurationProperties("swagger")
public class SwaggerProperties {

    /**
     * 是否开启swagger,生产环境配置关闭
     */
    private Boolean enable;

}

增加配置

swagger:
  enable: true

附:pom依赖

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="/POM/4.0.0"
         xmlns:xsi="http:///2001/XMLSchema-instance"
         xsi:schemaLocation="/POM/4.0.0 /xsd/maven-4.0.">
    <modelVersion>4.0.0</modelVersion>

    <groupId></groupId>
    <artifactId>Swagger3</artifactId>
    <version>1.0-SNAPSHOT</version>

    <parent>
        <groupId></groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.3.</version>
    </parent>

    <dependencies>
        <dependency>
            <groupId></groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId></groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>
        <dependency>
            <groupId></groupId>
            <artifactId>commons-lang3</artifactId>
            <version>3.11</version>
        </dependency>
        <dependency>
            <groupId></groupId>
            <artifactId>lombok</artifactId>
        </dependency>
    </dependencies>
</project>