在当今的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：用于描述请求参数，包括参数名、参数类型、必须性等信息。
@ApiModel：用于描述JavaBean类。
@ApiParam：用于描述参数信息。
@ApiResponses：用于描述API的响应，包括HTTP状态码、响应数据等信息。
@ApiProperty：用于描述JavaBean类的属性信息。
四、查看API文档
在完成了上述的配置之后，我们启动这个Spring Boot应用，并访问http://localhost:8080/swagger-ui.html。我们就可以在浏览器中查看到生成的API文档了。在这里我们可以查看到我们刚刚编写的API的详细信息，包括请求方法、请求参数、返回结果等等。同时，Swagger也能够生成一个请求和响应的示例流，方便开发者们进行引用和测试。
在这里，我们使用Spring Boot和Swagger来构建RESTful API文档。使用这样的方式，开发者们能够更加快速地构建和管理自己的API文档，提升开发的效率和可维护性。
