【マイクロサービスのAPI管理】 SwaggerでAPI文書管理を拡張する - Springboot3 第11回

2023年10月4日 11:57

はじめに

こんにちは、今日はマイクロサービスのAPI管理するためにSwaggerでAPI文書管理を拡張します。超簡単なので、ゆっくりしても大丈夫です。

まず、簡単に概要を把握して実装しましょう。

OpenAPIの概念

OpenAPIは、RESTful APIを設計、文書化、テスト、管理するためのオープンな標準仕様であり、機械可読形式のAPIマニュアルを提供します。OpenAPI仕様はYAMLまたはJSON形式でAPIを記述し、クライアントとサーバー間の通信を効果的に定義するのに役立ちます。

Swaggerの概念

SwaggerはOpenAPI仕様を実装するためのツールの一つで、開発者とAPIオーナーがAPIを設計、文書化、管理するのに役立ちます。

メリット

文書化と可読性
OpenAPIとSwaggerを使用すると、APIドキュメントを自動的に生成し、シンプルなUIを提供することができるので、ユーザーと開発者がAPIを簡単に理解して使用することができます。

一貫性
OpenAPI仕様を使用すると、API設計と文書化が一貫して維持されます。これにより、さまざまなチームや開発者間のコラボレーションが向上します。

統合とテスト
Swagger UIや他のツールを介してAPIを視覚化し、テストすることができるので、開発者はAPIを迅速にテストし、デバッグすることができます。

デメリット

学習曲線
最初はOpenAPIとSwaggerの概念と使い方を理解するのが難しいかもしれません。

修正と更新の難しさ
APIの仕様が変更されたときに、それを更新して同期するプロセスは面倒な場合があります。

大規模APIの複雑さ
大規模で複雑なAPIの場合、Swaggerファイルが複雑になり、メンテナンスが難しくなる可能性があります。

部署サービスのAPI文書化

依存性追加

	<dependency>
			<groupId>org.springdoc</groupId>
			<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
			<version>2.1.0</version>
		</dependency>

「DepartmentServiceApplication」でAP定義

ｎ@OpenAPIDefinition(
		info = @Info(
				title = "department Service REST APIs",
				description = "Department Service REST APIs Documentation",
				version = "v1.0",
				contact = @Contact(
						name = "ahahaha",
						email = "abc@gmail.com",
						url = "https://www.abc.net"
				),
				license = @License(
						name = "Apache 2.0",
						url = "https://www.abc.net"
				)
		),
		externalDocs = @ExternalDocumentation(
				description = "Department-Service Doc",
				url = "https://www.abc.com"
		)
)
@SpringBootApplication
public class DepartmentServiceApplication {

DepartmentControllerとDTOのカスタマイズ

＠Tag、＠Operation、＠ApiResponseアノテーションをつける。

同じ順番(pom.xml > ***ServiceApplication > Controller > DTO )で「Employee Service」、「Organization Service」を作成します。

Githubにコミット・プシュ

最後に

Swaggerの使用方法を忘れないように、簡単に部署、職員、組織サビスまで拡張して、API文書管理機能を追加しました。

Swaggerを利用すれば、APIのドキュメント化、APIのテスト、APIの管理とモニタリングができるので、マイクロサービスのAPI管理に積極的に使ってみましょう。

エンジニアファーストの会社 株式会社CRE-CO
ソンさん

【参考】

[Udemy] Building Microservices with Spring Boot & Spring Cloud