Swagger的使用方法详解

一、Swagger简介

Swagger是一种流行的API开发工具，它可以用来生成和管理RESTful服务的API文档，并允许用户通过UI界面来互动性地测试API请求和响应。Swagger提供了许多有用的功能，包括API模型的定义、文档的生成、代码生成、UI界面、测试、监控等。Swagger的目标是简化API的设计、开发和维护，提升API的可读性和可用性，增强API的开放性和互操作性。

二、Swagger的安装和配置

Swagger可以在Java、JavaScript、Go、Python、C#等多种语言中使用，本文以Java为例介绍其安装和配置过程。

1. Maven依赖

<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

在Spring Boot的主类中，添加@EnableSwagger2注解以开启Swagger支持。

@SpringBootApplication
@EnableSwagger2
public class Application {
   ...
}

3. 配置Swagger

在application.properties或application.yml文件中，添加如下的Swagger配置：

swagger:
  title: My API
  description: My awesome API
  version: 1.0.0
  contact:
    name: My Team
    url: https://myteam.com
    email: team@myteam.com

这些配置将告诉Swagger如何在API文档中显示标题、描述、版本、联系人等信息。

三、使用Swagger生成API文档

当Swagger在Spring Boot应用程序中启用后，可以通过访问http://localhost:8080/swagger-ui.html来获取Swagger UI界面和API文档。在Swagger UI中，可以看到所有控制器和操作的列表。

1. 创建API实例

在接下来的例子中，我们将展示如何创建一个简单的API，并将其加入到Swagger文档中。在src/main/java/com.example.demo/controller包中，创建一个名为PersonController的类，代码如下：

@RestController
@RequestMapping("/person")
@Api(value="人员管理接口",tags={"PersonController"})
public class PersonController {

    @ApiOperation(value="获取所有人员信息", notes="获取所有人员信息")
    @GetMapping("/")
    public List getAll() {
        ...
    }

    @ApiOperation(value="根据ID获取人员信息", notes="根据ID获取人员信息")
    @ApiImplicitParam(name = "id", value = "人员ID", required = true, dataType = "Long", paramType = "path")
    @GetMapping("/{id}")
    public Person getById(@PathVariable long id) {
        ...
    }

    @ApiOperation(value="添加人员信息", notes="添加人员信息")
    @PostMapping("/")
    public void add(@RequestBody Person person) {
        ...
    }

    @ApiOperation(value="更新人员信息", notes="更新人员信息")
    @ApiImplicitParam(name = "id", value = "人员ID", required = true, dataType = "Long", paramType = "path")
    @PutMapping("/{id}")
    public void update(@PathVariable long id, @RequestBody Person person) {
        ...
    }

    @ApiOperation(value="删除人员信息", notes="删除人员信息")
    @ApiImplicitParam(name = "id", value = "人员ID", required = true, dataType = "Long", paramType = "path")
    @DeleteMapping("/{id}")
    public void delete(@PathVariable long id) {
        ...
    }

}

  

在上面的代码中，我们使用了@RestController注解来声明控制器，并使用@RequestMapping注解来定义控制器的路径。我们还使用了@Api注解来为控制器定义一个名称和一组标记。方法部分使用了@ApiOperation、@ApiImplicitParam等注解，来定义每个操作的名称、说明、输入、输出等。这些注解将使Swagger API文档具有更多的描述、关联和结构。

2. 访问Swagger UI界面

现在，我们已经创建了一个简单的API，并为其添加了Swagger注解，接下来我们可以访问http://localhost:8080/swagger-ui.html并查看生成的API文档。在Swagger UI中，可以看到PersonController的相关操作，包括获取所有人员信息、根据ID获取人员信息、添加人员信息、更新人员信息和删除人员信息。

3. 使用Swagger测试API

我们可以使用Swagger UI界面来测试创建的API。在Swagger UI中，点击一个操作名称，展开该操作的详情。在其中，我们可以填写测试请求参数、指定请求头、查看响应结果等。

例如，我们可以在获取所有人员信息的操作中，点击“Try it out”按钮，在“Response Body”中查看响应结果。

[
  {
    "id": 1,
    "name": "Alice",
    "age": 20
  },
  {
    "id": 2,
    "name": "Bob",
    "age": 30
  },
  {
    "id": 3,
    "name": "Charlie",
    "age": 40
  }
]

4. 下载API代码

Swagger还可以生成API的代码和客户端库。在Swagger UI中，点击右上角的“Generate Client”按钮，在弹出的对话框中选择要生成的代码语言、设置输出目录和选项等，点击“Generate”按钮，Swagger将为您生成代码和客户端库。

四、Swagger的高级用法

1. 支持OAuth2.0认证

Swagger可以通过OAuth2.0认证方式来保护API，以避免未经授权的访问。在Spring Security配置中，可以通过@EnableOAuth2注解启用OAuth2认证，然后在Swagger配置中添加认证的相关参数，如下所示：

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .securitySchemes(Arrays.asList(securityScheme()))
                .securityContexts(Arrays.asList(securityContext()))
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("My API")
                .description("My awesome API")
                .version("1.0.0")
                .contact(new Contact("My Team", "https://myteam.com", "team@myteam.com"))
                .build();
    }

    private SecurityScheme securityScheme() {
        GrantType grantType = new AuthorizationCodeGrantBuilder()
                .tokenEndpoint(new TokenEndpointBuilder().url("http://localhost:8080/oauth/token").build())
                .tokenRequestEndpoint(
                        new TokenRequestEndpointBuilder().url("http://localhost:8080/oauth/authorize").build())
                .build();

        SecurityScheme oauth = new OAuthBuilder().name("spring_oauth")
                .grantTypes(Arrays.asList(grantType))
                .scopes(Arrays.asList(scopes()))
                .build();
        return oauth;
    }

    private SecurityContext securityContext() {
        return SecurityContext.builder()
                .securityReferences(Arrays.asList(new SecurityReference("spring_oauth", scopes()))).forPaths(PathSelectors.any())
                .build();
    }

    private AuthorizationScope[] scopes() {
        AuthorizationScope[] scopes = { 
                new AuthorizationScope("read", "for read operations"),
                new AuthorizationScope("write", "for write operations") };
        return scopes;
    }

}

2. 支持多国语言

Swagger可以用来生成多国语言的API文档。在Swagger配置中，可以添加参数包含多国语言文本，例如：

@Configuration
public class SwaggerConfig {

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

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("My API")
                .description("My awesome API")
                .version("1.0.0")
                .contact(new Contact("My Team", "https://myteam.com", "team@myteam.com"))
                .termsOfServiceUrl("https://myteam.com/terms")
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                .extensions(Collections.singletonList(new StringVendorExtension("language", "en")))
                .build();
    }

}

3. 支持上传下载文件

Swagger支持在API中上传下载文件。在操作参数中，使用@ApiParam注解来定义文件上传参数类型：

@ApiOperation(value="上传文件", notes="上传文件")
@PostMapping("/upload")
public void upload(@RequestParam("file") @ApiParam(name = "file", value = "上传的文件") MultipartFile file) {
    ...
}

@ApiOperation(value="下载文件", notes="下载文件")
@PostMapping("/download")
public void download(@RequestParam("path") @ApiParam(name = "path", value = "文件路径") String path, HttpServletResponse response) {
    ...
}

4. 支持API版本控制

Swagger支持对API进行版本控制。在配置中，指定API的版本号即可：

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    private static final String[] PRODUCES_AND_CONSUMES = { MediaType.APPLICATION_JSON_VALUE };

    @Bean
    public Docket apiV1() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("v1")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.ant("/v1/**"))
                .build()
                .apiInfo(apiInfo())
                .produces(Arrays.asList(PRODUCES_AND_CONSUMES))
                .consumes(Arrays.asList(PRODUCES_AND_CONSUMES));
    }

    @Bean
    public Docket apiV2() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("v2")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.ant("/v2/**"))
                .build()
                .apiInfo(apiInfo())
                .produces(Arrays.asList(PRODUCES_AND_CONSUMES))
                .consumes(Arrays.asList(PRODUCES_AND_CONSUMES));
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("My API")
                .description("My awesome API")
                .version("1.0.0")
                .contact(new Contact("My Team", "https://myteam.com", "team@myteam.com"))
                .build();
    }

}

5. 支持分组管理API

Swagger支持将API分组管理。在配置中，使用Docket的groupName来指定API所属分组，例如：

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    private static final String[] PRODUCES_AND_CONSUMES = { MediaType.APPLICATION_JSON_VALUE };

    @Bean
    public Docket apiA() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("Group A")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller.a"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo())
                .produces(Arrays.asList(PRODUCES_AND_CONSUMES))
                .consumes(Arrays.asList(PRODUCES_AND_CONSUMES));
    }

    @Bean
    public Docket apiB() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("Group B")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller.b"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo())
                .produces(Arrays.asList(PRODUCES_AND_CONSUMES))
                .consumes(Arrays.asList(PRODUCES_AND_CONSUMES));
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("My API")
                .description("My awesome API")