Swagger3 速通指南：用一杯奶茶的时间构建 API 文档

Springboot 中的 Swagger3：快速入门

在现代的软件开发中，API 文档对于 API 提供者和使用者都至关重要。Swagger3 作为一款流行的 API 文档生成工具，以其强大的功能和简洁的语法而备受开发者喜爱。本篇博客将带你快速入门 Swagger3，教你如何在 Springboot 项目中集成 Swagger3，构建出美观、实用的 API 文档。

环境搭建

准备工作

• 安装 Java JDK 1.8 或更高版本
• 安装并配置 Maven 或 Gradle 构建工具
• 创建一个新的 Springboot 项目

添加依赖

在项目的 pom.xml 或 build.gradle 文件中添加 Swagger3 的依赖：

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

配置 Swagger3

配置 YAML 文档

在项目的 resources 文件夹下创建 swagger.yaml 文件，并添加以下内容：

openapi: 3.0.1
info:
  title: My API
  version: 1.0.0

添加 Swagger UI

在 Springboot 项目的入口类中添加以下代码来启用 Swagger UI：

@SpringBootApplication
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

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

使用 Swagger3

在你的 Springboot 项目中，使用 @ApiOperation、@ApiParam 等注解来为你的 API 接口添加注释，Swagger3 将根据这些注释自动生成 API 文档。例如：

@RestController
@RequestMapping("/api")
public class MyController {

    @ApiOperation(value = "获取用户信息")
    @GetMapping("/user/{id}")
    public User getUser(@ApiParam(value = "用户ID", required = true) @PathVariable Long id) {
        return new User();
    }
}

启动项目

运行 Springboot 项目，访问 http://localhost:8080/swagger-ui.html 即可查看生成的 Swagger3 API 文档。

总结

通过本篇博客，你已经学会了如何在 Springboot 项目中集成 Swagger3，并使用 Swagger3 为你的 API 接口自动生成美观、实用的文档。赶快去实践一下吧，用一杯奶茶的时间，成为 API 文档小能手！

常见问题解答

1. Swagger3 和 Swagger2 有什么区别？

Swagger3 是 Swagger 的最新版本，它带来了许多新功能和改进，例如支持 OpenAPI 3.0、改进的文档外观和更友好的用户界面。

2. 如何自定义 Swagger3 UI 的外观？

你可以通过配置 Swagger UI 的主题和选项来自定义其外观。请查看 Swagger UI 官方文档了解更多信息。

3. 如何为 Swagger3 添加认证？

你可以使用 Swagger Security Annotations 或 Spring Security 来为 Swagger3 添加认证。请查看 Swagger 官方文档了解更多信息。

4. 如何解决 Swagger3 中的 CORS 问题？

在 Springboot 项目中，你可以通过在 WebConfig 类中添加以下代码来解决 CORS 问题：

@Configuration
@EnableWebMvc
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**")
                .allowedOrigins("*")
                .allowedMethods("*")
                .allowedHeaders("*")
                .allowCredentials(true);
    }
}

5. Swagger3 是否支持文档版本控制？

是的，Swagger3 支持文档版本控制。你可以通过在 swagger.yaml 文件中指定不同的版本号来实现。例如：

openapi: 3.0.1
info:
  title: My API
  version: 1.0.0
tags:
  - name: User
    description: User related operations
paths:
  /users:
    get:
      tags: [User]
      summary: Get all users
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        email:
          type: string