Java API 開発での Swagger の使用に関する詳細な紹介

Java API 開発において、Swagger は非常に便利なツールです。 Swagger は、RESTful Web サービスを記述、設計、生成するためのオープンソース API フレームワークです。開発者が API とパラメーターを説明するのに役立つ一連の注釈を提供します。この記事では、Java API 開発で Swagger を使用する方法について詳しく説明します。

1. Swagger のインストール

Swagger は、Maven を使用して Java プロジェクトに統合できます。次の Maven 依存関係を使用して、Swagger をプロジェクトに追加できます:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

さらに、Swagger UI を生成するには、次の依存関係を追加する必要があります:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2. Swagger の構成

Java アプリケーションでは、Swagger を構成する必要があります。これを行うには、Swagger を初期化する構成クラスを作成します。

@Configuration
@EnableSwagger2
public class SwaggerConfig {    
    @Bean
    public Docket api() { 
        return new Docket(DocumentationType.SWAGGER_2)  
          .select()                                  
          .apis(RequestHandlerSelectors.any())              
          .paths(PathSelectors.any())                          
          .build();                                          
    }
}

上記のコードでは、Swagger のメイン インターフェイスである Docket Bean を定義しました。これを使用して Swagger API のタイプを指定し、それをアプリケーションの URL にマップします。

3. Swagger アノテーションの追加

これで、Java API に Swagger アノテーションを追加できるようになりました。一般的に使用される Swagger アノテーションとその用途を次に示します。

• @Api: API 全体を記述するために使用されます。
• @ApiOperation: API オペレーションを記述するために使用されます。
• @ApiParam: 操作パラメータを記述するために使用されます。
• @ApiModel: API を提供するために使用されるモデル属性。
• @ApiModelProperty: API モデルを記述するために使用されるプロパティ。

これらのアノテーションは、クラス、メソッド、フィールド、メソッド パラメーターに配置でき、value 属性とnotes 属性を使用して API コメントに関する情報を提供できます。

たとえば、次のコード スニペットがある場合:

@RestController
@RequestMapping("/users")
public class UserController {
    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        // code to get user
    }
}

Swagger アノテーションを使用して getUser メソッドを記述することができます:

@RestController
@RequestMapping("/users")
@Api(value="用户管理", tags="用户管理")
public class UserController {
 
    @GetMapping("/{id}")
    @ApiOperation(value="获取用户信息", notes="根据用户ID获取用户信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
    public User getUser(@PathVariable Long id) {
        // code to get user
    }
}

上記のコードでは、@ を使用しました。 API および @ApiOperation アノテーション。 @Api アノテーションは、名前やラベルを含む API 全体を記述するために使用されます。 @ApiOperation アノテーションは、操作の名前と操作に関する注意事項を記述するために使用されます。

4. Swagger UI の生成

Java アプリケーションが Swagger および Swagger アノテーションを使用して構成されたので、Swagger UI を使用して API を表示およびテストできます。

これを行うには、SwaggerConfig クラスの @Bean アノテーションの下に次の行を追加します。

@Configuration
@EnableSwagger2
public class SwaggerConfig {    
    @Bean
    public Docket api() { 
        return new Docket(DocumentationType.SWAGGER_2)  
          .select()                                  
          .apis(RequestHandlerSelectors.any())              
          .paths(PathSelectors.any())                          
          .build();                                          
    }

    @Bean
    public UiConfiguration uiConfig() {
        return UiConfigurationBuilder.builder()
            .docExpansion(DocExpansion.LIST)
            .build();
    }
}

これにより、Swagger UI を構成するための uiConfig() Bean が追加されます。上記のコードを使用して、DocExpansion を LIST に設定し、UI ですべてのアクションがデフォルトで展開されるようにします。

5. アプリケーションの開始

これで、Swagger と Swagger アノテーションが構成され、SwaggerConfig クラスで Swagger UI が生成されました。次のコマンドを使用してアプリケーションを起動できます。

$ mvn spring-boot:run

Swagger のデフォルト設定に従って、ブラウザから Swagger UI にアクセスできます。 http://localhost:8080/swagger-ui.html に移動すると、Swagger UI にすでに API が表示されていることがわかります。

6. API のテスト

最後に、Swagger UI を使用して API をテストできます。 [試してみる] ボタンをクリックすると、Swagger UI が API にリクエストを自動的に送信し、UI にレスポンスが表示されます。

この記事では、Java API 開発で Swagger を使用する方法を紹介しました。 Swagger を使用すると、API の記述とテストを簡単に行うことができ、読みやすく使いやすいドキュメントを生成できます。 Java 開発者であれば、API の開発とテストを簡素化するために Swagger を試してみることをお勧めします。

以上がJava API 開発での Swagger の使用に関する詳細な紹介の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。