【由chatgpt3.5写的swagger入门教程】_swagger 3.5 requiredmode

Swagger整合Spring Boot

Swagger是一个API文档生成工具，能够根据API的注释生成相应的API文档。Spring Boot是一个快速构建应用程序的框架，能够快速开发RESTful API。

在本文中，我们将介绍如何将Swagger整合到Spring Boot应用程序中，以便生成API文档并进行API测试。

特点

• 自动生成API文档
• 提供UI界面进行API测试
• 支持多种编程语言和框架
• 方便扩展

入门案例

本节将介绍如何在Spring Boot应用程序中使用Swagger生成API文档并进行API测试。

添加依赖

在 pom.xml 文件中添加以下依赖：

xmlCopy code<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>
1
2
3
4
5
6
7
8
9
10

这些依赖将允许我们使用Swagger生成API文档，并使用Swagger UI界面测试API。

配置Swagger

创建一个名为 SwaggerConfig.java 的配置类，添加以下代码：

javaCopy code@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}
1
2
3
4
5
6
7
8
9
10
11
12

这个类将创建一个Docket bean，用于配置Swagger。@EnableSwagger2 注解将启用Swagger。

编写Controller

创建一个简单的Controller，用于演示Swagger的用法。例如：

javaCopy code@RestController
@RequestMapping("/api")
public class HelloController {
    @ApiOperation(value = "打招呼", notes = "向指定名称的人打招呼")
    @ApiImplicitParam(name = "name", value = "姓名", required = true, dataType = "String", paramType = "path")
    @GetMapping("/hello/{name}")
    public String hello(@PathVariable String name) {
        return "Hello, " + name + "!";
    }
}
1
2
3
4
5
6
7
8
9
10

在这个Controller中，我们使用了 @ApiOperation 和 @ApiImplicitParam 注解，这些注解用于描述API的名称、参数、返回值等信息。这些注解的作用将在下一节中介绍。

测试API

启动应用程序，访问 http://localhost:8080/swagger-ui.html，可以看到Swagger UI界面。在这个界面中，我们可以看到应用程序中所有的API，包括我们刚刚创建的 /api/hello/{name} 接口。

点击 /api/hello/{name}，进入API页面，可以看到这个接口的详细信息，包括名称、参数、返回值等。我们可以在这个页面中进行API测试，输入参数并点击“Try it out!”按钮，即可测试API。

使用注解描述API

Swagger使用注解来描述API的名称、参数、返回值等信息。下面是常用的注解及其用法：

• @ApiOperation：用于描述API的名称、说明等信息。常用属性包括 value 和 notes。

javaCopy code
@ApiOperation(value = "打招呼", notes = "向指定名称的人打招呼")
1
2

• @ApiImplicitParam：用于描述API的参数信息。常用属性包括 name、value、required、dataType 和 paramType。

javaCopy code
@ApiImplicitParam(name = "name", value = "姓名", required = true, dataType = "String", paramType = "path")
1
2

• @ApiImplicitParams：用于描述多个API参数。

javaCopy code@ApiImplicitParams({
    @ApiImplicitParam(name = "name", value = "姓名", required = true, dataType = "String", paramType = "path"),
    @ApiImplicitParam(name = "age", value = "年龄", required = true, dataType = "int", paramType = "query")
})
1
2
3
4

• @ApiResponse：用于描述API的返回值信息。

javaCopy code
@ApiResponse(code = 200, message = "成功", response = String.class)
1
2

• @ApiResponses：用于描述多个API返回值。

javaCopy code@ApiResponses(value = {
    @ApiResponse(code = 200, message = "成功", response = String.class),
    @ApiResponse(code = 400, message = "请求参数错误", response = ErrorResponse.class),
    @ApiResponse(code = 500, message = "系统内部错误", response = ErrorResponse.class)
})
1
2
3
4
5

• @ApiModel：用于描述一个数据模型。

javaCopy code@ApiModel(value = "用户信息", description = "用户信息")
public class User {
    @ApiModelProperty(value = "姓名", required = true)
    private String name;
    @ApiModelProperty(value = "年龄", required = true)
    private int age;
    // 省略getter和setter方法
}
1
2
3
4
5
6
7
8

• @ApiModelProperty：用于描述一个属性。

javaCopy code@ApiModelProperty(value = "姓名", required = true)
private String name;
1
2

配置Swagger

我们可以通过 Docket 类来配置Swagger。以下是常用的配置项及其说明：

• select()：返回一个 ApiSelectorBuilder 实例，用于配置扫描哪些API。
• apis(RequestHandlerSelectors.any())：扫描所有API。
• apis(RequestHandlerSelectors.basePackage("com.example"))：扫描指定包下的API。
• paths(PathSelectors.any())：扫描所有路径。
• paths(PathSelectors.ant("/api/**"))：扫描 /api/ 开头的路径。
• build()：返回一个 Docket 实例。

javaCopy code@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.any())
            .build();
}
1
2
3
4
5
6
7
8

测试API

启动应用程序，访问 http://localhost:8080/swagger-ui.html，可以看到Swagger UI界面。在这个界面中，我们可以看到应用程序中所有的API。

点击其中一个API，可以看到其详细信息，包括请求参数、响应结果等。我们可以在这个界面中测试API。

结语

本教程介绍了Swagger的基本概念、特点以及如何整合Spring Boot。Swagger是一个非常强大的API文档工具，可以让我们更方便地管理和测试API。如果您正在开发一个API项目，强烈建议您使用Swagger来管理您的API文档。

完整的示例代码请参考 GitHub 仓库。