在当今的Web开发中，RESTful API已经成为了开发者们非常流行的方式来构建网站和应用。使用RESTful API，开发者能够构建出清晰明了的API，更方便的与其他应用或服务进行交互。而为了能够更好地管理和维护这些API，文档的编写和管理也成为了非常关键的一部分。
Spring Boot是一款快速构建Java应用的框架，具有简单、快速、易于扩展的特点。而Swagger则是一款专门用于设计、构建和文档化RESTful API的工具，能够快速地生成RESTful API文档，并自动生成API的请求和响应的示例流。
本文将会介绍如何使用Spring Boot和Swagger来构建RESTful API文档。
一、创建Spring Boot项目
首先，我们需要使用Spring Initializr创建一个Spring Boot项目，可以通过https://start.spring.io/来进行创建。在这里，我们选择Web和Swagger 2这两个依赖。创建完成后，我们导入项目到集成开发环境中，并在pom.xml中添加Swagger的依赖：
<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>
二、创建RESTful API
在这里我们创建一个简单的RESTful API，用于生成一个随机数。
我们在Controller中添加一个方法：
@RestController
public class NumberController {
@ApiOperation(value = "Generate a random number between 1 and 100")
@RequestMapping(value = "/generateNumber", method = RequestMethod.GET)
public ResponseEntity<Integer> generateNumber() {
Random random = new Random();
int randomNumber = random.nextInt(100) + 1;
return ResponseEntity.ok(randomNumber);
}
}需要注意的是，在类上不仅需要添加@RestController注解，还需要使用@Api注解来描述这个Controller的作用。
反编译后的内容：
package com.example.demo.controller;
import io.swagger.annotations.ApiOperation;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import java.util.Random;
@RestController
public class NumberController
{
public NumberController()
{
}
@ApiOperation(value="Generate a random number between 1 and 100")
@RequestMapping(value="/generateNumber", method=RequestMethod.GET)
public ResponseEntity generateNumber()
{
Random random = new Random();
int randomNumber = random.nextInt(100) + 1;
return ResponseEntity.ok(new Integer(randomNumber));
}
}三、配置Swagger
在完成了对应的Controller的开发之后，我们需要进行Swagger的配置。在Spring Boot的配置文件application.properties中添加Swagger的相关配置。
#指定Swagger API扫描的路径
swagger.basePackage=com.example.demo.controller
#应用名称
swagger.title=Spring Boot Swagger Example
#版本号
swagger.version=1.0.0
#描述信息
swagger.description=This is a demo service for Spring Boot Swagger.
#联系人信息
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注解。
@ApiIgnore：用于被忽略的API，不会在生成的API文档中显示。
@ApiOperation：用于描述具体的API操作，包括方法名、请求方法、请求参数、返回对象等信息，可以放在方法上面或者是类上面。
@ApiImplicitParam：用于描述请求参数，包括参数名、参数类
.........................................................