使用Spring Boot和Swagger來建立RESTful API文檔

在當今的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中文網其他相關文章！