Spring Boot がインターフェイスドキュメントの自動生成を実装する方法

Web アプリケーションを開発する場合、インターフェイスのドキュメントは非常に重要な部分であり、API の機能と使用法をすぐに理解するのに役立ち、他の開発者やチームと共同作業するための重要なツールでもあります。ただし、インターフェイスのドキュメントを手動で作成して保守するのは面倒な作業であり、省略やエラーが発生しやすいです。この目的を達成するために、Spring Boot が提供するいくつかのツールとフレームワークを使用してインターフェイスドキュメントを自動的に生成し、開発効率とドキュメントの品質を向上させることができます。

ここに画像の説明を挿入

Swagger の概要

Swagger は、インターフェイスドキュメント、API テスト、およびクライアントコードを自動的に生成できる RESTful API ドキュメント生成ツールです。注釈を通じて API 情報をマークし、その情報に基づいて API ドキュメントとテストページを生成します。Swagger は、Java や Spring Boot などの複数の言語とフレームワークをサポートしています。この記事では、Swaggerを利用してSpring Bootインターフェースドキュメントの自動生成を実現する方法を紹介します。

Swagger の統合

依存関係を追加する

まず、Swagger の依存関係を Spring Boot プロジェクトに追加する必要があります。pom.xml ファイルに次の依存関係を追加します。

<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>

このうち、springfox-swagger2 は Swagger の中心的な依存関係であり、springfox-swagger-ui は Swagger の UI コンポーネントであり、インターフェイスドキュメントとテストページを表示するために使用されます。

Swagger の構成

Swagger の依存関係を追加した後、Swagger の関連情報を設定する必要があります。Spring Boot アプリケーションの構成クラスでは、@EnableSwagger2 アノテーションを使用して Swagger を有効にし、@Configuration アノテーションを使用して構成クラスを指定できます。具体的なコードは次のとおりです。

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    
    
   @Bean
   public Docket api() {
    
    
       return new Docket(DocumentationType.SWAGGER_2)
               .select()
               .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
               .paths(PathSelectors.any())
               .build()
               .apiInfo(apiInfo());
   }

   private ApiInfo apiInfo() {
    
    
       return new ApiInfoBuilder()
               .title("Spring Boot接口文档")
               .description("Spring Boot接口文档")
               .version("1.0.0")
               .build();
   }
}

上記のコードでは、SwaggerConfig という構成クラスを作成し、@EnableSwagger2 アノテーションを使用して Swagger を有効にしました。API メソッドでは、Docket オブジェクトを使用して、スキャンされた API パッケージ、API パス、ドキュメント情報などの Swagger 関連情報を構成します。このうち、RequestHandlerSelectors.basePackage はスキャンする API パッケージを指定し、PathSelectors.any はすべての API パスをスキャンするように指定します。apiInfo メソッドでは、ApiInfoBuilder オブジェクトを使用して、ドキュメントのタイトル、説明、バージョン番号などの情報を構成します。

タグAPI情報

Swagger を構成した後、Swagger アノテーションを API メソッドに追加して、API 情報をマークする必要があります。一般的に使用される Swagger アノテーションは次のとおりです。

@Api: API の名前、説明、バージョン番号など、API をマークするために使用される情報。
@ApiOperation: API メソッドをマークするために使用される情報 (メソッド名、説明、HTTP メソッドなど)。
@ApiParam: パラメーターの名前、説明、データ型など、API メソッドのパラメーター情報をマークするために使用されます。
@ApiResponse: 応答 HTTP ステータスコード、説明、応答データ型など、API メソッドの応答情報をマークするために使用されます。
@ApiModel: データモデルの名前、説明、フィールド情報など、API のデータモデル情報をマークするために使用されます。
@ApiModelProperty: フィールドの名前、説明、データ型など、API データモデルのフィールド情報をマークするために使用されます。

Swagger アノテーションを使用した例を次に示します。

@RestController
@RequestMapping("/users")
@Api(value = "用户管理", tags = "用户管理API")
public class UserController {
    
    
   @Autowired
   private UserService userService;

   @GetMapping("")
   @ApiOperation(value = "获取所有用户", notes = "获取所有用户的信息")
   public List<User> getUsers() {
    
    
       return userService.getUsers();
   }

   @GetMapping("/{id}")
   @ApiOperation(value = "获取用户信息", notes = "根据ID获取用户的信息")
   public User getUserById(@PathVariable("id") long id) {
    
    
       return userService.getUserById(id);
   }

   @PostMapping("")
   @ApiOperation(value = "创建用户", notes = "创建一个新的用户")
   public User createUser(@RequestBody User user) {
    
    
       return userService.createUser(user);
   }

   @PutMapping("/{id}")
   @ApiOperation(value = "更新用户信息", notes = "根据ID更新用户的信息")
   public User updateUser(@PathVariable("id") long id, @RequestBody User user) {
    
    
       return userService.updateUser(id, user);
   }

   @DeleteMapping("/{id}")
   @ApiOperation(value = "删除用户", notes = "根据ID删除用户")
   public void deleteUser(@PathVariable("id") long id) {
    
    
       userService.deleteUser(id);
   }
}

上記のコードでは、@Api アノテーションを使用して、API の名前や説明などの API の情報をマークしました。各 API メソッドでは、@ApiOperation アノテーションを使用して、メソッドの名前、HTTP メソッド、メソッドの説明などのメソッドの情報をマークします。パラメーターでは、 @ApiParam アノテーションを使用して、パラメーターの名前、説明、データ型などのパラメーターの情報をマークします。戻り値では、@ApiResponse アノテーションを使用して、応答の HTTP ステータスコード、応答の説明、応答データのタイプなどの応答情報をマークします。

インターフェイスのドキュメントにアクセスする

上記の手順を完了したら、Spring Boot アプリケーションを起動し、http://localhost:8080/swagger-ui.html にアクセスして、Swagger によって生成されたインターフェイスドキュメントとテストページを確認できます。ドキュメントページでは、API 情報、パラメーター、応答などの詳細情報を確認したり、インターフェイスのテストを実行したりできます。テストページでは、HTTP メソッド、入力パラメータ、リクエストヘッダーなどの情報を選択し、リクエストを送信して返された結果を表示できます。

Swagger の共通構成

上記の基本構成に加えて、Swagger はさまざまなニーズを満たすために他の多くの構成オプションも提供します。一般的に使用される Swagger 構成オプションをいくつか示します。

構成グループ

実際の開発では、アプリケーションに複数の API グループが含まれる場合があり、各グループは異なる機能モジュールまたはビジネスシナリオに対応します。API の管理と検索を容易にするために、Swagger のグループ化機能を使用して API をグループで表示できます。構成クラスでは、Docket の groupName メソッドを使用して API のグループ名を指定できます。具体的なコードは次のとおりです。

@Bean
public Docket api() {
    
    
    return new Docket(DocumentationType.SWAGGER_2)
        .groupName("users")
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
        .paths(PathSelectors.any())
        .build()
        .apiInfo(apiInfo());
}

上記のコードでは、groupName メソッドを使用して、API のグループ名を「users」として指定します。

グローバルパラメータを設定する

実際の開発では、認証情報、API バージョン番号などのグローバルパラメーターをリクエストヘッダー、パスパラメーター、またはリクエスト本文で使用する場合があります。各 API メソッドでこれらのパラメーターを繰り返し追加しないようにするには、Swagger のグローバルパラメーター関数を使用して、これらのパラメーターを API ドキュメントに追加します。構成クラスでは、Docket の globalOperationParameters メソッドを使用してグローバルパラメーターを指定できます。具体的なコードは次のとおりです。

@Bean
public Docket api() {
    
    
    List<Parameter> parameters = new ArrayList<>();
    parameters.add(new ParameterBuilder()
        .name("Authorization")
        .description("认证信息")
        .modelRef(new ModelRef("string"))
        .parameterType("header")
        .required(false)
        .build());
    parameters.add(new ParameterBuilder()
        .name("version")
        .description("API版本号")
        .modelRef(new ModelRef("string"))
        .parameterType("query")
        .required(false)
        .build());

    return new Docket(DocumentationType.SWAGGER_2)
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
        .paths(PathSelectors.any())
        .build()
        .globalOperationParameters(parameters)
        .apiInfo(apiInfo());
}

上記のコードでは、globalOperationParameters メソッドを使用して、Authorization と version という 2 つのグローバルパラメーターを追加します。このうち、ParameterBuilder はパラメータオブジェクトの作成に使用され、name はパラメータ名、description はパラメータの説明、modelRef はパラメータの種類、parameterType はパラメータの位置を指定します。Docket の globalOperationParameters メソッドでは、パラメータリストを Swagger に渡し、API ドキュメントに追加します。

ドキュメントスタイルを構成する

デフォルトでは、Swagger によって生成されたドキュメントスタイルはプロジェクトスタイルと一致しない可能性がありますが、スタイルファイルをカスタマイズすることでドキュメントの外観を変更できます。Spring Boot アプリケーションでは、パブリックディレクトリを作成し、その中に swagger-ui.html ファイルと swagger.css ファイルを作成できます。swagger-ui.html ファイルでは、カスタムスタイルファイルを導入し、デフォルトスタイルをオーバーライドできます。具体的なコードは次のとおりです。

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Swagger UI</title>
    <link rel="stylesheet" type="text/css" href="swagger.css">
    <linkrel="stylesheet" type="text/css" href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.10.0/swagger-ui.css" >
</head>
<body>
<div id="swagger-ui"></div>

<script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.10.0/swagger-ui-bundle.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.10.0/swagger-ui-standalone-preset.js"></script>
<script>
    window.onload = function() {
      
      
        const ui = SwaggerUIBundle({
      
      
            url: "/v2/api-docs",
            dom_id: '#swagger-ui',
            presets: [
                SwaggerUIBundle.presets.apis,
                SwaggerUIStandalonePreset
            ],
            layout: "BaseLayout",
            deepLinking: true,
            showExtensions: true,
            showCommonExtensions: true,
            docExpansion: "none"
        })
    }
</script>
</body>
</html>

上記のコードでは、カスタムスタイルファイル swagger.css と、Swagger が提供する公式スタイルファイル swagger-ui.css を head タグに導入しました。body タグで、swagger-ui という ID を持つ div を作成し、その中に Swagger JavaScript ファイルを導入しました。JavaScript では、SwaggerUIBundle オブジェクトを使用して Swagger UI のインスタンスを作成し、url プロパティを「/v2/api-docs」に設定して、API ドキュメントの URL アドレスを示します。dom_id 属性は Swagger UI のレンダリング位置を指定し、presets 属性は使用するプリセットテンプレートを指定し、layout 属性はドキュメントのレイアウトを指定し、deepLinking 属性はディープリンクを使用するかどうかを指定し、showExtensions 属性と showCommonExtensions 属性は拡張属性を表示します。カスタムスタイルファイルでは、CSS ルールを使用して、フォントサイズ、色、背景の変更など、ドキュメントの外観を変更できます。

要約する

この記事では、Swagger を使用して Spring Boot インターフェイスドキュメントを自動的に生成する方法について説明します。まず、Swagger の依存関係を追加し、構成クラスで Swagger を有効にしました。次に、アノテーションを使用して API 情報をマークし、インターフェイスのドキュメントとテストページにアクセスします。さらに、構成グループ化、グローバルパラメーター、ドキュメントスタイルなど、Swagger の一般的な構成オプションも導入しました。Swagger を使用すると、開発効率とドキュメントの品質が大幅に向上し、API ドキュメントの管理と維持が向上します。