Spring Boot と Swagger を使用して RESTful API ドキュメントを構築する

今日の Web 開発では、RESTful API は開発者が Web サイトやアプリケーションを構築するための非常に一般的な方法となっています。 RESTful API を使用すると、開発者は他のアプリケーションやサービスとより便利にやり取りするための明確な API を構築できます。これらの API をより適切に管理および保守するには、ドキュメントの作成と管理も非常に重要な部分になっています。

Spring Boot は、シンプル、高速、拡張が容易な Java アプリケーションを迅速に構築するためのフレームワークです。 Swagger は、RESTful API の設計、構築、文書化に特に使用されるツールで、RESTful API ドキュメントを迅速に生成し、API リクエストと応答のサンプル フローを自動的に生成できます。

この記事では、Spring Boot と Swagger を使用して RESTful API ドキュメントを構築する方法を紹介します。

1. Spring Boot プロジェクトの作成

まず、Spring Initializr を使用して Spring Boot プロジェクトを作成する必要があります (https://start.spring.io/ から作成できます)。ここでは、Web と Swagger 2 という 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>

2. RESTful API の作成

ここでは、単純な RESTful API を作成します。乱数を生成するためのAPI。

コントローラーにメソッドを追加します:

@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 アノテーションも使用する必要があることに注意してください。このコントローラーの役割について説明します。

逆コンパイルされた内容:

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));
    }
}

3. Swagger の構成

対応するコントローラーの開発が完了したら、Swagger を構成する必要があります。 Swagger 関連の構成を Spring Boot 構成ファイル application.properties に追加します。

#指定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: Spring MVC の @Controller および @RequestMapping アノテーションと同様に、コントローラーの役割を説明するために使用されます。

@ApiIgnore: 無視された API に使用され、生成された API ドキュメントには表示されません。

@ApiOperation: メソッド名、リクエスト メソッド、リクエスト パラメータ、戻りオブジェクト、およびメソッドまたはクラスに配置できるその他の情報を含む、特定の API 操作を記述するために使用されます。

@ApiImplicitParam: パラメーター名、パラメーターのタイプ、必要性、その他の情報を含むリクエスト パラメーターを記述するために使用されます。

@ApiModel: JavaBean クラスを記述するために使用されます。

@ApiParam: パラメータ情報を記述するために使用されます。

@ApiResponses: HTTP ステータス コード、応答データ、その他の情報を含む API 応答を記述するために使用されます。

@ApiProperty: JavaBean クラスのプロパティ情報を記述するために使用されます。

4. API ドキュメントの表示

上記の構成が完了したら、Spring Boot アプリケーションを起動し、http://localhost:8080/swagger-ui.html にアクセスします。生成された API ドキュメントをブラウザーで表示できます。ここでは、リクエスト メソッド、リクエスト パラメータ、返された結果など、作成したばかりの API の詳細情報を表示できます。同時に、Swagger はリクエストとレスポンスのサンプル ストリームを生成して、開発者が参照してテストできるようにすることもできます。

ここでは、Spring Boot と Swagger を使用して RESTful API ドキュメントを構築します。この方法を使用すると、開発者は独自の API ドキュメントをより迅速に構築および管理できるため、開発効率と保守性が向上します。

以上がSpring Boot と Swagger を使用して RESTful API ドキュメントを構築するの詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。