掌握Swagger 2.0，从基础配置到高效使用，一文全解析

最佳答案

Swagger 2.0 是一个富强的 RESTful API 文档跟交互式测试东西，它可能帮助开辟者疾速生成、测试跟文档化他们的 API。本文将单方面剖析 Swagger 2.0 的基本设置，以及怎样高效利用它。

一、Swagger 2.0 简介

Swagger 2.0 是一个基于 OpenAPI 标准的 API 管理东西。它可能主动扫描代码中的 API 接口，并生成一份包含接口描述、恳求方法、参数、呼应示例等外容的文档。Swagger 2.0 支撑多种编程言语，包含 Java、C#、Python 等。

二、Swagger 2.0 的上风

1. 主动生成文档：节俭了保护本钱。
2. 交互式界面：便利开辟者调试接口。
3. 参数校验、认证等功能扩大年夜。

三、Swagger 2.0 在 Spring Boot 中的设置

1. 增加依附

在 Spring Boot 项目中，须要增加 Swagger 2.0 的依附。以下是在 pom.xml 文件中增加依附的示例：

<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>

2. 创建设置类

创建一个 Swagger 设置类，用于设置 Swagger。

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                .paths(PathSelectors.any())
                .build();
    }
}

3. 设置 YAML 文件

在 application.yml 或 application.properties 文件中设置 Swagger。

springfox:
  documentation:
    swagger:
      v2:
        host: yourapp.abc.com/project-name

4. 启动 Swagger UI

在浏览器中拜访 http://localhost:8080/swagger-ui.html，即可看到 Swagger UI。

四、Swagger 2.0 的高等功能

1. 自定义 API 信息：经由过程设置类中的 apiInfo() 方法，可能自定义 API 的标题、描述、版本等信息。
2. 参数校验：经由过程注解 @Valid 跟 @RequestBody，可能对恳求参数停止校验。
3. 认证：经由过程设置类中的 securitySchemes() 方法，可能设置 API 的认证方法。

五、总结

Swagger 2.0 是一个功能富强的 API 文档跟测试东西，可能帮助开辟者疾速生成、测试跟文档化他们的 API。经由过程本文的剖析，信赖你曾经控制了 Swagger 2.0 的基本设置跟高效利用方法。