Spring Boot项目中利用Swagger管理RESTful API文档的创建步骤

当今的 web 开发中，restful api 已成为开发者构建网站和应用的流行方式。开发者利用 restful api 可构建清晰明了的 api，便于与其他应用或服务交互。为更好地管理和维护这些 api，文档的编写和管理成为关键部分。

Spring Boot 是用于快速构建 Java 应用的框架，它具备简单、快速且易于扩展的特性。Swagger 是专门用来设计、构建以及文档化 RESTful API 的工具，它可以迅速生成 RESTful API 文档，并且能够自动生成 API 的请求和响应的示例流。

本文将介绍构建 RESTful API 文档的方法，其中会用到 Spring Boot 和 Swagger。

一、创建Spring Boot项目

首先，我们得利用 Spring Initializr 去创建一个 Spring Boot 项目，创建途径可以是[具体创建方式]。在这当中，我们选取了 Web 和 Swagger 2 这两项依赖。创建完毕后，我们把项目导入到集成开发环境里，并且在 pom.xml 中添加 Swagger 的依赖。

io.springfoxspringfox-swagger22.9.2io.springfoxspringfox-swagger-ui2.9.2

登录后复制

二、创建RESTful API

我们在这里创建一个简单的 RESTful API，这个 API 是用来生成一个随机数的。

我们在Controller中添加一个方法：

@RestController
类名为 NumberController 的类，它在程序中有着特定的作用和功能。这个类主要用于处理与数字相关的操作和逻辑。它可能包含各种方法，用于对数字进行计算、转换、比较等操作。通过这个类，可以方便地对数字进行各种处理，以满足不同的业务需求。
 
@ApiOperation 的值为“生成 1 到 100 之间的随机数”
@RequestMapping 的 value 属性值为 "/generateNumber"，其 method 属性值为 RequestMethod.GET
   public ResponseEntity generateNumber() {
       Random random = new Random();
生成一个 1 到 100 之间的随机数，这个随机数被存储在变量 randomNumber 中，通过调用 random 对象的 nextInt(100) 方法再加上 1 得到。
返回一个状态码为 200 的响应实体，其中包含一个随机数。
   }
}

登录后复制

需要注意的是，在类上不仅要添加@RestController 这个注解，而且要使用@Api 注解来对这个 Controller 的作用进行描述。

反编译后的内容：

该语句是关于 Java 代码中包的定义，表明在 com.example.demo 包下有一个控制器类。它指定了类所在的包路径，用于组织和管理代码结构，方便代码的维护和引用。
引入 io.swagger.annotations.ApiOperation；
从 org.springframework.http 这个包中导入 ResponseEntity 类。
通过这个注解，可以将特定的 HTTP 请求映射到相应的处理方法上。
在 org.springframework.web.bind.annotation 包中，有一个用于处理请求的注解为 RequestMethod 。
引入了 org.springframework.web.bind.annotation.RestController 这个类。 它在 Spring 框架中用于处理 HTTP 请求并返回响应。 通常被用于创建 RESTful Web 服务。 可以通过注解的方式将类标记为 RESTful 控制器。 这样，Spring 框架就能自动识别和处理该类中的 HTTP 请求。 它提供了方便的方式来构建和管理 Web 应用程序的接口。 使得开发人员能够更轻松地创建和部署 Web 服务。 减少了开发过程中的繁琐工作。 提高了开发效率。
import java.util.Random;
@RestController
public class NumberController
{
    public NumberController()
    {
    }
ApiOperation 的值为“生成 1 到 100 之间的随机数”。
@RequestMapping 的 value 属性为 "/generateNumber"，method 属性为 RequestMethod.GET。
公共响应实体生成数字。
    {
        Random random = new Random();
生成一个 1 到 100 之间的随机数，将其赋值给 randomNumber 变量，这个随机数是通过 random 对象的 nextInt(100) 方法生成后再加 1 得到的。
返回一个状态码为 200 的响应实体，该实体包含一个新生成的随机数转换后的整数。
    }
}

登录后复制

三、配置Swagger

完成对应的 Controller 的开发之后，接着要进行 Swagger 的配置。在 Spring Boot 的配置文件 application.properties 里添加与 Swagger 相关的配置。

#指定Swagger API扫描的路径
swagger 的 basePackage 为 com.example.demo.controller
 
#应用名称
Spring Boot Swagger 的标题是 Spring Boot Swagger Example 。
 
#版本号
swagger.version=1.0.0
 
#描述信息
 
#联系人信息
swagger.contact.name=John Doe
swagger 的 contact.url 为 http://www.example.com
swagger 的 contact 中的 email 为 john.doe@example.com

登录后复制

注解说明：

@Api 是用来描述 Controller 的作用的，它与 Spring MVC 中的@Controller 和@RequestMapping 注解类似。

用于被忽略的 API，在生成的 API 文档中不会显示。

@ApiOperation 用于对具体的 API 操作进行描述，其中包含方法名、请求方法、请求参数以及返回对象等信息，它既可以放置在方法之上，也可以放置在类之上。

@ApiImplicitParam 用来对请求参数进行描述，其中包含参数名这一信息，也包含参数类型的信息，还包含必须性等相关信息。

@ApiModel：用于描述JavaBean类。

@ApiParam：用于描述参数信息。

@ApiResponses 的作用是描述 API 的响应，其中包含 HTTP 状态码以及响应数据等相关信息。

@ApiProperty 的作用是对 JavaBean 类的属性信息进行描述。

四、查看API文档

完成上述配置之后，我们启动这个 Spring Boot 应用，接着访问 :8080/swagger-ui.html 。这样我们就能在浏览器中查看到生成的 API 文档了。在此处，我们可以看到刚刚编写的 API 的详细信息，其中包含请求方法、请求参数、返回结果等。Swagger能够生成请求的示例流，方便开发者进行引用和测试。同时，Swagger也能够生成响应的示例流，方便开发者进行引用和测试。

我们在这里利用 Spring Boot 和 Swagger 构建 RESTful API 文档。通过这种方式，开发者能够更迅速地构建并管理自身的 API 文档，从而提高开发的效率与可维护性。