在當今的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文檔，提升開發的效率和可維護性。
以上是使用Spring Boot和Swagger來建立RESTful API文檔的詳細內容。更多資訊請關注PHP中文網其他相關文章！
