Java API 開発において、Swagger は非常に便利なツールです。 Swagger は、RESTful Web サービスを記述、設計、生成するためのオープンソース API フレームワークです。開発者が API とパラメーターを説明するのに役立つ一連の注釈を提供します。この記事では、Java API 開発で 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>
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 にマップします。
これで、Java API に Swagger アノテーションを追加できるようになりました。一般的に使用される Swagger アノテーションとその用途を次に示します。
これらのアノテーションは、クラス、メソッド、フィールド、メソッド パラメーターに配置でき、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 アノテーションは、操作の名前と操作に関する注意事項を記述するために使用されます。
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 ですべてのアクションがデフォルトで展開されるようにします。
これで、Swagger と Swagger アノテーションが構成され、SwaggerConfig クラスで Swagger UI が生成されました。次のコマンドを使用してアプリケーションを起動できます。
$ mvn spring-boot:run
Swagger のデフォルト設定に従って、ブラウザから Swagger UI にアクセスできます。 http://localhost:8080/swagger-ui.html に移動すると、Swagger UI にすでに API が表示されていることがわかります。
最後に、Swagger UI を使用して API をテストできます。 [試してみる] ボタンをクリックすると、Swagger UI が API にリクエストを自動的に送信し、UI にレスポンスが表示されます。
この記事では、Java API 開発で Swagger を使用する方法を紹介しました。 Swagger を使用すると、API の記述とテストを簡単に行うことができ、読みやすく使いやすいドキュメントを生成できます。 Java 開発者であれば、API の開発とテストを簡素化するために Swagger を試してみることをお勧めします。
以上がJava API 開発での Swagger の使用に関する詳細な紹介の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。