swagger2 使用指南，一分钟搞定！

用 Swagger2 生成 RESTful API 文档的全面指南

简介

随着 RESTful API 的广泛采用，清晰且全面的 API 文档对于开发人员来说变得至关重要。Swagger2 作为一款流行的 API 文档生成工具，可以帮助您快速、轻松地创建详细、美观的 API 文档。本博客将指导您如何配置 Swagger2 并解决常见的默认地址失效问题。

配置 Swagger2

1. 添加依赖

在您的项目 pom.xml 文件中，添加以下依赖：

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

2. 配置 Swagger2

在 application.yml 配置文件中，添加以下配置：

swagger:
  enabled: true
  title: 项目名称
  description: 项目
  version: 1.0.0

3. 扫描接口

在您的 Spring Boot 应用程序的启动类中，添加以下代码：

@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)
        .apiInfo(apiInfo())
        .select()
        .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
        .paths(PathSelectors.any())
        .build();
  }

  private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
        .title("项目名称")
        .description("项目")
        .version("1.0.0")
        .build();
  }
}

解决 Swagger2 默认地址失效问题

如果您遇到 Swagger2 默认地址失效的情况，可以尝试以下方法：

1. 检查项目是否已成功启动

2. 检查 Swagger2 配置是否正确

3. 检查防火墙或代理服务器是否阻止了对 Swagger2 的访问

4. 尝试修改 Swagger2 的默认地址

swagger:
  enabled: true
  path: /api-docs

结论

通过遵循本指南，您可以成功配置 Swagger2 并生成详细的 RESTful API 文档。Swagger2 不仅可以帮助您理解 API 功能，还可以促进开发人员之间的协作和知识共享。

常见问题解答

1. Swagger2 和 OpenAPI 有什么区别？

Swagger2 是 OpenAPI 规范的早期版本。OpenAPI 3.0 是 Swagger2 的继任者，并提供了一些增强功能。

2. 如何在 Swagger2 中添加示例请求和响应？

可以使用 @ApiResponse 注解为 API 方法添加示例请求和响应。

3. 如何在 Swagger2 中生成 Markdown 文档？

您可以使用 springfox-swagger-ui 模块为 Swagger UI 生成 Markdown 文档。

4. 如何使用 Swagger2 测试 API？

Swagger2 提供了一个集成的 API 测试工具，称为 Swagger Editor。

5. Swagger2 是否支持 WebSockets？

不，Swagger2 不支持 WebSockets。但是，OpenAPI 3.0 支持 WebSockets。