Swagger入门：新手必读教程

概述

Swagger入门教程详细介绍了Swagger这一流行的API文档工具，帮助开发者自动生成、解析和可视化RESTful风格的API文档。文章不仅解释了Swagger的主要功能和优势，还提供了从安装配置到创建第一个Swagger文档的详细步骤。

Swagger入门：新手必读教程 Swagger简介

什么是Swagger

Swagger 是一个流行的 API 文档工具，它帮助开发者自动生成、解析和可视化 RESTful 风格的 API 文档。Swagger 主要通过两种方式来实现这一点：一种是通过使用 OpenAPI 规范，另一种是通过使用 Swagger 注解。Swagger 提供了丰富的 API 文档功能，使得开发者能够快速地创建和维护 API 文档，确保前后端开发人员之间的高效沟通。

Swagger的主要功能和优势

Swagger 的主要功能包括以下几点：

1. 自动生成 API 文档：Swagger 可以根据代码自动生成详细的 API 文档，减少了手动编写文档的工作量。
2. 交互式文档：Swagger 提供了交互式的文档界面，允许开发者直接在文档中测试 API，确保 API 的正确性。
3. 版本控制：Swagger 支持版本控制，使得开发者可以轻松地管理不同版本的 API。
4. 可视化工具：Swagger 提供了可视化的 API 测试工具，使得 API 的调试变得更加方便。
5. 支持多种编程语言：Swagger 支持多种编程语言，包括 Java、Python、Node.js 等，使得不同开发团队能够使用其熟悉的编程语言。

Swagger 的主要优势包括以下几点：

1. 提高开发效率：通过自动生成 API 文档，Swagger 可以显著提高开发效率，减少手动编写文档的时间。
2. 提高 API 的可维护性：Swagger 提供了详细的 API 文档，使得 API 更加容易维护。
3. 提高团队协作效率：Swagger 提供的交互式文档界面使得前后端开发人员可以更加高效地协作。
4. 提高 API 的可测试性：Swagger 提供了可视化的测试工具，使得 API 的测试变得更加方便。

安装与配置Swagger

下载和安装Swagger工具

Swagger 的安装通常分为两步：下载和安装。以下是安装 Swagger 的步骤。

下载 Swagger

1. 下载 Swagger 的官方客户端，可以从 Swagger 的 GitHub 仓库下载最新的版本。下载链接如下：

   • Swagger 的 GitHub 仓库
2. 选择合适的版本进行下载。Swagger 支持多种编程语言，你可以根据自己的需求选择对应的版本进行下载。

安装 Swagger

1. 安装 Java 环境。Swagger 是基于 Java 的，因此需要先安装 Java 环境。你可以从 Oracle 官网下载 Java 并安装。
2. 执行 Swagger 的安装命令。在下载完 Swagger 的客户端后，你可以使用命令行工具执行如下命令来安装 Swagger：

   mvn install

   该命令会将 Swagger 的客户端安装到本地的 Maven 仓库中，以便后续使用。

配置开发环境

配置开发环境主要包括配置 Swagger 的运行环境和配置 Swagger 的工作目录。

配置 Swagger 的运行环境

1. 创建一个新的 Maven 项目。你可以使用 IntelliJ IDEA 或 Eclipse 等 IDE 创建一个新的 Maven 项目。
2. 在项目的 pom.xml 文件中添加 Swagger 的依赖。Swagger 的依赖如下所示：

   <dependencies>
       <dependency>
           <groupId>io.swagger</groupId>
           <artifactId>swagger-core</artifactId>
           <version>2.0.0</version>
       </dependency>
       <dependency>
           <groupId>io.swagger</groupId>
           <artifactId>swagger-annotations</artifactId>
           <version>2.0.0</version>
       </dependency>
       <dependency>
           <groupId>io.swagger</groupId>
           <artifactId>swagger-jaxrs</artifactId>
           <version>2.0.0</version>
       </dependency>
       <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>
   </dependencies>

   这些依赖包含了 Swagger 的核心库、注解库和 JAX-RS 集成库。

配置 Swagger 的工作目录

1. 创建一个新的 Swagger 配置文件。你可以创建一个新的 Java 类来配置 Swagger 的工作目录，例如 SwaggerConfig.java。

2. 配置 Swagger 的基础信息。在 SwaggerConfig.java 类中配置 Swagger 的基本信息，例如 API 版本、API 标题、API 描述等。如下所示是一个简单的配置示例：

   import io.swagger.annotations.ApiInfo;
   import io.swagger.annotations.ApiOperation;
   import io.swagger.annotations.Api;
   import io.swagger.annotations.ApiParam;
   import springfox.documentation.builders.ApiInfoBuilder;
   import springfox.documentation.service.ApiInfo;
   import springfox.documentation.spi.DocumentationType;
   import springfox.documentation.spring.web.plugins.Docket;
   import springfox.documentation.builders.PathSelectors;
   import springfox.documentation.builders.RequestHandlerSelectors;
   import springfox.documentation.spi.service.contexts.SecurityContext;
   import springfox.documentation.swagger2.annotations.EnableSwagger2;
   
   @EnableSwagger2
   public class SwaggerConfig {
   
       public Docket api() {
           return new Docket(DocumentationType.SWAGGER_2)
               .apiInfo(apiInfo())
               .select()
               .apis(RequestHandlerSelectors.any())
               .paths(PathSelectors.any())
               .build();
       }
   
       private ApiInfo apiInfo() {
           return new ApiInfoBuilder()
               .title("API 文档")
               .description("这是一个 Swagger API 文档")
               .version("1.0.0")
               .build();
       }
   }

   该代码配置了 Swagger 的基本信息，包括 API 的标题、描述、版本等。

创建第一个Swagger文档

在配置好开发环境后，你可以开始创建第一个 Swagger 文档。

创建基本的API描述

1. 创建一个新的 API 端点。假设你正在开发一个简单的 RESTful API 服务，例如一个用户管理服务。你可以在 UserController.java 类中创建一个新的 API 端点，如下所示：

   import org.springframework.web.bind.annotation.GetMapping;
   import org.springframework.web.bind.annotation.RequestMapping;
   import org.springframework.web.bind.annotation.RequestParam;
   import org.springframework.web.bind.annotation.RestController;
   
   @RestController
   @RequestMapping("/users")
   public class UserController {
   
       @GetMapping("/hello")
       @ApiOperation(value = "返回一个欢迎信息", notes = "这个 API 返回一个欢迎信息")
       @ApiParam(value = "用户名", required = true)
       public String hello(@RequestParam String name) {
           return "Hello, " + name + "!";
       }
   }

   该代码创建了一个简单的 API 端点 /users/hello，返回一个字符串 "Hello, Swagger!"。

2. 添加 Swagger 注解。为了将上述 API 端点添加到 Swagger 文档中，你需要在该端点上添加 Swagger 注解，如下所示：

   import io.swagger.annotations.Api;
   import io.swagger.annotations.ApiOperation;
   import io.swagger.annotations.ApiResponses;
   import io.swagger.annotations.ApiResponse;
   import io.swagger.annotations.ApiParam;
   
   @RestController
   @RequestMapping("/users")
   @Api(value = "UserController", description = "用户管理 API")
   public class UserController {
   
       @GetMapping("/hello")
       @ApiOperation(value = "返回一个欢迎信息", notes = "这个 API 返回一个欢迎信息")
       @ApiParam(value = "用户名", required = true)
       @ApiResponses(value = {
           @ApiResponse(code = 200, message = "返回一个欢迎信息", response = String.class),
           @ApiResponse(code = 400, message = "无效的请求参数", response = String.class)
       })
       public String hello(@RequestParam String name) {
           return "Hello, " + name + "!";
       }
   }

   该代码在 UserController 类和 hello 方法上添加了 Swagger 注解，以描述 API 的基本信息。

使用Swagger注解

1. 添加描述信息。除了基本的描述信息，你还可以在 API 端点上添加更多的描述信息，例如请求参数、响应数据等。如下所示是一个添加描述信息的示例：

   import io.swagger.annotations.Api;
   import io.swagger.annotations.ApiOperation;
   import io.swagger.annotations.ApiResponses;
   import io.swagger.annotations.ApiResponse;
   import io.swagger.annotations.ApiParam;
   
   @RestController
   @RequestMapping("/users")
   @Api(value = "UserController", description = "用户管理 API")
   public class UserController {
   
       @GetMapping("/hello")
       @ApiOperation(value = "返回一个欢迎信息", notes = "这个 API 返回一个欢迎信息")
       @ApiParam(value = "用户名", required = true)
       @ApiResponses(value = {
           @ApiResponse(code = 200, message = "返回一个欢迎信息", response = String.class),
           @ApiResponse(code = 400, message = "无效的请求参数", response = String.class)
       })
       public String hello(@RequestParam String name) {
           return "Hello, " + name + "!";
       }
   }

   该代码在 hello 方法上添加了一个请求参数 name，并提供了描述信息。

2. 配置响应数据。除了请求参数，你还可以在 API 端点上配置响应数据。如下所示是一个配置响应数据的示例：

   import io.swagger.annotations.Api;
   import io.swagger.annotations.ApiOperation;
   import io.swagger.annotations.ApiResponses;
   import io.swagger.annotations.ApiResponse;
   import io.swagger.annotations.ApiParam;
   
   @RestController
   @RequestMapping("/users")
   @Api(value = "UserController", description = "用户管理 API")
   public class UserController {
   
       @GetMapping("/hello")
       @ApiOperation(value = "返回一个欢迎信息", notes = "这个 API 返回一个欢迎信息")
       @ApiParam(value = "用户名", required = true)
       @ApiResponses(value = {
           @ApiResponse(code = 200, message = "返回一个欢迎信息", response = String.class),
           @ApiResponse(code = 400, message = "无效的请求参数", response = String.class)
       })
       public String hello(@RequestParam String name) {
           return "Hello, " + name + "!";
       }
   }

   该代码在 hello 方法上配置了响应数据，包括成功响应和错误响应。

Swagger文档的基本元素

路径和操作

在 Swagger 文档中，路径和操作是非常重要的元素。路径定义了 API 的 URL 路径，而操作定义了路径上的 HTTP 方法及其对应的描述信息。

路径

路径定义了 API 的 URL 路径，通常使用 @Path 注解来定义。例如，以下代码定义了一个路径 /users：

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/users")
public class UserController {

    @GetMapping("/hello")
    public String hello(@RequestParam String name) {
        return "Hello, " + name + "!";
    }
}

这段代码定义了一个路径 /users，并在该路径下定义了一个 GET 方法 /hello。

操作

操作定义了路径上的 HTTP 方法及其对应的描述信息。通常使用 @ApiOperation 注解来定义操作。例如，以下代码定义了一个 GET 方法 /hello：

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;

@RestController
@RequestMapping("/users")
@Api(value = "UserController", description = "用户管理 API")
public class UserController {

    @GetMapping("/hello")
    @ApiOperation(value = "返回一个欢迎信息", notes = "这个 API 返回一个欢迎信息")
    public String hello(@RequestParam String name) {
        return "Hello, " + name + "!";
    }
}

这段代码定义了一个 GET 方法 /hello，并在该方法上添加了描述信息。

参数和响应

除了路径和操作，参数和响应也是非常重要的元素。参数定义了请求参数，而响应定义了响应数据。通常使用 @ApiParam 和 @ApiResponse 注解来定义参数和响应。

参数

参数定义了请求参数，通常使用 @ApiParam 注解来定义。例如，以下代码定义了一个请求参数 name：

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;

@RestController
@RequestMapping("/users")
@Api(value = "UserController", description = "用户管理 API")
public class UserController {

    @GetMapping("/hello")
    @ApiOperation(value = "返回一个欢迎信息", notes = "这个 API 返回一个欢迎信息")
    @ApiParam(value = "用户名", required = true)
    public String hello(@RequestParam String name) {
        return "Hello, " + name + "!";
    }
}

这段代码定义了一个请求参数 name，并提供了描述信息。

响应

响应定义了响应数据，通常使用 @ApiResponse 注解来定义。例如，以下代码定义了一个成功响应和一个错误响应：

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import io.swagger.annotations.ApiResponses;
import io.swagger.annotations.ApiResponse;

@RestController
@RequestMapping("/users")
@Api(value = "UserController", description = "用户管理 API")
public class UserController {

    @GetMapping("/hello")
    @ApiOperation(value = "返回一个欢迎信息", notes = "这个 API 返回一个欢迎信息")
    @ApiParam(value = "用户名", required = true)
    @ApiResponses(value = {
        @ApiResponse(code = 200, message = "返回一个欢迎信息", response = String.class),
        @ApiResponse(code = 400, message = "无效的请求参数", response = String.class)
    })
    public String hello(@RequestParam String name) {
        return "Hello, " + name + "!";
    }
}

这段代码定义了一个成功响应和一个错误响应。

测试Swagger API文档

使用Swagger UI进行测试

Swagger 提供了一个叫做 Swagger UI 的工具，可以用来测试 Swagger 文档中的 API。以下是使用 Swagger UI 进行测试的步骤。

启动Swagger UI

1. 创建一个新的 Swagger UI 项目。你可以使用 Maven 创建一个新的项目，并添加 Swagger UI 的依赖。

   <dependencies>
       <dependency>
           <groupId>io.swagger</groupId>
           <artifactId>swagger-core</artifactId>
           <version>2.0.0</version>
       </dependency>
       <dependency>
           <groupId>io.swagger</groupId>
           <artifactId>swagger-annotations</artifactId>
           <version>2.0.0</version>
       </dependency>
       <dependency>
           <groupId>io.swagger</groupId>
           <artifactId>swagger-jaxrs</artifactId>
           <version>2.0.0</version>
       </dependency>
       <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>
   </dependencies>

   该依赖包含了 Swagger UI 的相关库。

2. 启动 Swagger UI。启动 Swagger UI 需要配置 Swagger 的 Web 应用程序，如下所示是一个简单的配置示例：

   import springfox.documentation.builders.PathSelectors;
   import springfox.documentation.builders.RequestHandlerSelectors;
   import springfox.documentation.spi.DocumentationType;
   import springfox.documentation.spring.web.plugins.Docket;
   import springfox.documentation.swagger2.annotations.EnableSwagger2;
   
   @EnableSwagger2
   public class SwaggerConfig {
   
       public Docket api() {
           return new Docket(DocumentationType.SWAGGER_2)
               .select()
               .apis(RequestHandlerSelectors.any())
               .paths(PathSelectors.any())
               .build();
       }
   }

   该代码配置了 Swagger 的 Web 应用程序，并启用了 Swagger UI。

使用Swagger UI测试API

启动 Swagger UI 后，你可以在浏览器中访问 Swagger UI 的界面来测试 API。例如，假设你在本地启动了 Swagger UI，可以访问以下 URL：

http://localhost:8080/swagger-ui.html

在 Swagger UI 的界面上，你可以看到你定义的 API 端点及其对应的描述信息。例如，假设你定义了一个 GET 方法 /users/hello，如下所示：

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import io.swagger.annotations.ApiResponses;
import io.swagger.annotations.ApiResponse;

@RestController
@RequestMapping("/users")
@Api(value = "UserController", description = "用户管理 API")
public class UserController {

    @GetMapping("/hello")
    @ApiOperation(value = "返回一个欢迎信息", notes = "这个 API 返回一个欢迎信息")
    @ApiParam(value = "用户名", required = true)
    @ApiResponses(value = {
        @ApiResponse(code = 200, message = "返回一个欢迎信息", response = String.class),
        @ApiResponse(code = 400, message = "无效的请求参数", response = String.class)
    })
    public String hello(@RequestParam String name) {
        return "Hello, " + name + "!";
    }
}

在 Swagger UI 的界面上，你可以看到该 API 端点及其对应的描述信息。你可以直接在界面上测试该 API，如下图所示：

点击 "Try it out" 按钮，Swagger UI 将会发送一个 GET 请求到该 API 端点，并在界面上显示响应结果。

验证API的功能

除了使用 Swagger UI 进行测试，你还可以验证 API 的功能。例如，你可以在本地启动 Swagger UI 后，使用 Postman 或者浏览器发送请求到 API 端点，并验证响应结果。

使用Postman测试API

1. 创建一个新的 POST 请求。在 Postman 中创建一个新的 POST 请求，并设置 URL 为 http://localhost:8080/users/hello。

   POST http://localhost:8080/users/hello

2. 设置请求参数。在请求参数中添加一个请求参数 name，其值为 "Swagger"。

   name=Swagger

3. 发送请求。点击 "Send" 按钮发送请求，并查看响应结果。

   HTTP/1.1 200 OK
   Content-Type: text/plain
   
   Hello, Swagger!

使用浏览器测试API

1. 打开浏览器。打开你的浏览器，并访问 http://localhost:8080/users/hello?name=Swagger。

   http://localhost:8080/users/hello?name=Swagger

2. 查看响应结果。浏览器将会显示响应结果 "Hello, Swagger!"。

常见问题解答

常见错误及解决方法

在使用 Swagger 时，可能会遇到一些常见的错误。以下是常见的错误及其解决方法。

错误1：Swagger UI 无法启动

错误描述：启动 Swagger UI 时，浏览器无法访问 Swagger UI 界面。

解决方法：检查 Swagger UI 的配置是否正确。例如，检查是否启用了 Swagger UI，是否配置了正确的路径等。确保 Swagger UI 的配置正确后，重新启动 Swagger UI。

错误2：API 端点无法访问

错误描述：在 Swagger UI 中测试 API 端点时，浏览器无法访问该端点。

解决方法：检查 API 端点的配置是否正确。例如，检查是否定义了正确的路径和 HTTP 方法，是否配置了正确的路径参数等。确保 API 端点的配置正确后，重新测试 API 端点。

常见问题与技巧分享

除了常见的错误，还有一些常见的问题和技巧分享。

问题1：如何配置复杂的请求参数和响应数据？

解决方法：使用 Swagger 提供的注解来配置复杂的请求参数和响应数据。例如，使用 @ApiParam 注解来配置请求参数，使用 @ApiResponse 注解来配置响应数据。

技巧1：如何自定义 Swagger UI 的样式？

技巧描述：你可以自定义 Swagger UI 的样式，以满足你的需求。例如，你可以修改 Swagger UI 的 CSS 文件，以改变界面的颜色等。

解决方法：在 Swagger UI 的配置中，你可以自定义 Swagger UI 的 HTML 模板，并修改相应的 CSS 文件。例如，你可以使用以下代码配置 Swagger UI 的 HTML 模板：

import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@EnableSwagger2
public class SwaggerConfig {

    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.any())
            .build()
            .uiConfiguration(new UiConfiguration(
                "/api-docs",
                true,
                true,
                "json",
                false,
                2,
                springfox.documentation.ui.UiConfigurationBuilder.builder().build()
            ));
    }
}

该代码配置了 Swagger UI 的 HTML 模板，并修改了相应的 CSS 文件。

技巧2：如何自定义 Swagger 文档的版本？

技巧描述：你可以自定义 Swagger 文档的版本，以满足你的需求。例如，你可以修改 Swagger 文档的版本号，以显示不同的版本信息。

解决方法：在 Swagger 文档的配置中，你可以自定义 Swagger 文档的版本。例如，你可以使用以下代码配置 Swagger 文档的版本：

import io.swagger.annotations.ApiInfo;
import io.swagger.annotations.ApiOperation;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@EnableSwagger2
public class SwaggerConfig {

    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.any())
            .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("API 文档")
            .description("这是一个 Swagger API 文档")
            .version("1.0.0")
            .build();
    }
}

该代码配置了 Swagger 文档的版本号为 "1.0.0"。

技巧3：如何自定义 Swagger 文档的描述信息？

技巧描述：你可以自定义 Swagger 文档的描述信息，以满足你的需求。例如，你可以修改 Swagger 文档的描述信息，以显示不同的描述信息。

解决方法：在 Swagger 文档的配置中，你可以自定义 Swagger 文档的描述信息。例如，你可以使用以下代码配置 Swagger 文档的描述信息：

import io.swagger.annotations.ApiInfo;
import io.swagger.annotations.ApiOperation;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@EnableSwagger2
public class SwaggerConfig {

    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.any())
            .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("API 文档")
            .description("这是一个 Swagger API 文档")
            .version("1.0.0")
            .contact(new springfox.documentation.service.Contact("作者", "http://example.com", "author@example.com"))
            .license("Apache 2.0")
            .build();
    }
}

该代码配置了 Swagger 文档的描述信息，包括作者、联系信息、许可证等。