Swaggerのドキュメント列挙型

投稿日: 2022-10-23 2022-10-23
タグ: Spring Web, Swagger

1. 概要

このチュートリアルでは、 swagger-maven-plugin を使用してSwaggerで列挙型を文書化し、生成されたJSON文書をSwaggerエディターで検証する方法を学習します。

2. Swaggerとは何ですか？

Swagger は、RESTベースのAPIを定義するためのオープンソースツールです。今日の世界では、ほとんどの組織がマイクロサービスとAPIファーストアプローチに移行しています。 Swaggerは、APIの設計と文書化に非常に便利です。また、API開発を支援するために、Swagger Editor、Swagger UI、SwaggerCodeGenなどのさまざまなツールも提供します。

また、SwaggerはOpenAPI仕様またはOASの実装であり、残りのAPI開発の一連の標準を定義します。その結果、世界中の組織がAPIを作成するプロセスを標準化するのに役立ちます。

アプリケーションによって生成されたJSONファイルも、OpenAPI仕様に従います。

SwaggerでのEnumの重要性を理解してみましょう。一部のAPIでは、ユーザーが事前定義された値の特定のセットに固執する必要があります。これらの事前定義された定数値は列挙型と呼ばれます。同様に、SwaggerがAPIを公開する場合、ユーザーがフリーテキストではなくこの事前定義されたセットから値を選択するようにします。 つまり、ユーザーが可能な値を認識できるように、swagger.jsonファイルに列挙型を文書化する必要があります。

3. 実装

REST APIの例を取り上げて、実装にジャンプしましょう。 POST APIを実装して、特定の役割の組織に従業員を雇用します。ただし、役割は、エンジニア、店員、運転手、または用務員のいずれかになります。

Role という名前の列挙型を作成し、employee roleのすべての可能な値を使用して、プロパティの1つとしてroleを持つクラスEmployeeを作成します。クラスとそれらの関係をよりよく理解するために、UML図を見てみましょう。

これをSwaggerで文書化するために、まず、アプリケーションでswagger-maven-pluginをインポートして構成します。次に、必要なアノテーションをコードに追加し、最後にプロジェクトをビルドして、生成されたSwaggerドキュメントまたはSwaggerエディターでswagger.jsonを確認します。

3.1. プラグインのインポートと構成

swagger-maven-plugin 、を使用し、アプリケーションのpom.xmlへの依存関係として追加する必要があります。

<dependency>
    <groupId>com.github.kongchen</groupId>
    <artifactId>swagger-maven-plugin</artifactId>
    <version>3.1.1</version>
</dependency>

また、このプラグインを構成して有効にするために、pom.xmlのプラグインセクションにプラグインを追加します。

locations ：このタグは、セミコロンで区切られた@Apiを含むパッケージまたはクラスを指定します
info ：このタグはAPIのメタデータを提供します。 Swagger-uiはこのデータを使用して情報を表示します
swaggerDirectory ：このタグは、swagger.jsonファイルのパスを定義します

<plugin>
    <groupId>com.github.kongchen</groupId>
    <artifactId>swagger-maven-plugin</artifactId>
    <version>3.1.1</version>
    <configuration>
        <apiSources>
            <apiSource>
                <springmvc>false</springmvc>
                <locations>com.baeldung.swaggerenums.controller</locations>
                <schemes>http,https</schemes>
                <host>baeldung.com</host>
                <basePath>/api</basePath>
                <info>
                    <title>Baeldung - Document Enum</title>
                    <version>v1</version>
                    <description>This is a Baeldung Document Enum Sample Code</description>
                    <contact>
                        <email>pmurria@baeldung.com</email>
                        <name>Test</name>
                    </contact>
                    <license>
                        <url>https://www.apache.org/licenses/LICENSE-2.0.html</url>
                        <name>Apache 2.0</name>
                    </license>
                </info>
                <swaggerDirectory>generated/swagger-ui</swaggerDirectory>
            </apiSource>
        </apiSources>
    </configuration>
    <executions>
        <execution>
            <phase>compile</phase>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
     </executions>
 </plugin>

3.2. 列挙型の文書化

Swaggerで列挙型を文書化するには、アノテーション@ApiModelを使用してモデルを宣言する必要があります。

この例では、 Engineer、Clerk、Driver、およびJanitorの4つの可能な値を持つ列挙型Roleを作成しました。この列挙型を文書化する必要があるため、@ApiModelを列挙型Roleに追加します。つまり、これによりSwaggerにモデルの存在が通知されます。 Employee クラスでは、Employeeに@ApiModelで注釈を付け、Roleに@ApiModelPropertyで注釈を付けます。

Employee、 Role、、HireControllerは次のようになります。

@ApiModel
public class Employee {
    @ApiModelProperty
    public Role role;

   // standard setters and getters
}

@ApiModel
public enum Role {
    Engineer, Clerk, Driver, Janitor;
}

次に、 @Path を“ / Hire” として使用してAPIを作成し、EmployeeモデルをhireEmployee[への入力パラメーターとして使用します。 X147X]メソッド。 @ApiをHireControllerに追加して、 swagger-maven-plugin が認識し、文書化のために検討する必要があります。

@Api
@Path(value="/hire")
@Produces({"application/json"})
public class HireController {

    @POST
    @ApiOperation(value = "This method is used to hire employee with a specific role")
    public String hireEmployee(@ApiParam(value = "role", required = true) Employee employee) {
        return String.format("Hired for role: %s", employee.role.name());
    }
}

3.3. Swaggerドキュメントの生成

プロジェクトをビルドしてSwaggerドキュメントを生成するには、次のコマンドを実行します。

mvn clean install

プラグインがビルドされると、swagger.jsonファイルがgenerated/swagger-uiまたはプラグインで構成された場所に生成されます。定義の下を見ると、従業員のプロパティ内に可能なすべての値とともに列挙型Roleが文書化されていることがわかります。

"definitions" : {
  "Employee" : {
    "type" : "object",
    "properties" : {
      "role" : {
        "type" : "string",
        "enum" : [ "Engineer", "Clerk", "Driver", "Janitor" ]
      }
    }
  }
}

次に、オンラインSwaggerエディターを使用して生成されたJSONを視覚化し、列挙型Roleを探します。

4. 結論

このチュートリアルでは、Swaggerとは何かについて説明し、OpenAPI仕様と組織のAPI開発におけるその重要性について学びました。また、 swagger-maven-plugin を使用して、列挙型を含むサンプルAPIを作成して文書化しました。最後に、出力を検証するために、Swaggerエディターを使用して生成されたJSONドキュメントを視覚化しました。

この実装は、GitHubのにあります。

getdocs

13036