ASP.NET Core の OpenAPIサポート

.NET Conf 2024 Fukuoka x Osaka にてお話させていただいた内容になります。
https://fukuten.connpass.com/event/333954/

Transcript

1. ASP.NET Core の OpenAPIサポート 2025/1/11 .NET Conf 2024 Fukuoka x Osaka
3. Toshimasa Hashiguchi Alterbooth.inc Webアプリケーション開発 Technology： C#、.NET、Azure、GitHub、XR Community： Fukuoka.NET、福岡XR部 X：@h455h1
4. OpenAPIの概要 - HTTP API の定義に使用される標準的なフォーマット - API のエンドポイント、リクエスト、レスポンスなどの情報を一貫して記述可能 - 機械にも人間にも優しい - さまざまな開発者やAPIベンダー、ツールがOpenAPIを使用して連携可能
5. ASP.NET Core 9.0のOpenAPIサポート - ASP.NET Coreでは、OpenAPIのサポートが組み込まれている - ASP.NET Coreアプリでは、Microsoft.AspNetCore.OpenApiパッケージを使用し て、アプリ内のエンドポイントに関する情報を生成 - 生成されたOpenAPIドキュメントは、エンドポイントまたはシリアル化されたファイル を通して公開
6. ASP.NET Core 9.0 Web API テンプレート（MinimalAPI） エンドポイントを アプリケーションに追加 DIコンテナーに登録 Microsoft.AspNetCore.OpenApiパッ ケージを介して提供
7. ASP.NET Core 9.0 Web API テンプレート（MinimalAPI） エンドポイントを アプリケーションに追加 DIコンテナーに登録 /openapi/v1.json
8. ASP.NET Core 9.0 Web API テンプレート（MinimalAPI） エンドポイントを アプリケーションに追加 DIコンテナーに登録
9. ASP.NET Core 8.0 Web API テンプレート との比較 Swaggerジェネレータを サービスコレクションに追加 APIドキュメントと Swagger UI を提 供するミドルウェアを有効化
10. なぜSwagger（Swashbuckle ）取り除かれたのか？ Swaggerジェネレータを サービスコレクションに追加 APIドキュメントと Swagger UI を提 供するミドルウェアを有効化 https://dev.to/eminvergil/an-alternative-to-swagger-in-dotnet-9-2jd6 1. メンテナンスの問題 2. ASP.NET Coreの進化 3. OpenAPIへのフォーカス 4. 代替ツールの提供 5. コミュニティ主導のイノベーションの促進
11. Swagger（Swashbuckle）を使用する https://learn.microsoft.com/ja-jp/aspnet/core/fundamentals/openapi/using-openapi-documents?view =aspnetcore-9.0&WT.mc_id=%3Fwt.mc_id%3DDT-MVP-5004827#use-swagger-ui-for-local-ad-hoc -testing
12. ASP.NET Core アプリに OpenAPI メタデータを含める Minimal API Controller Base WebAPI
13. ビルド時に OpenAPI ドキュメントを生成する - Microsoft.Extensions.ApiDescription.Serverパッケージをインストール - プロジェクトファイルで出力されるAPIドキュメントの場所を指定 - dotnet build
14. ビルド時に OpenAPI ドキュメントを生成する
15. CIパイプラインでごにょごにょできるってコト？
16. GitHub Actionsを使用してWikiのAPIドキュメントを自動更新する APIの更新 ビルド Wiki Push OpenAPI Document Markdown GitHub Actions
17. GitHub Actionsを使用してWikiのAPIドキュメントを自動更新する widdershins - OpenAPI仕様からMarkdownへの変換 - https://github.com/Mermade/widdershins
18. GitHub Actionsを使用してWikiのAPIドキュメントを自動更新する https://github.com/t0ottio13/sample-openapi-document-sync/actions
19. Demo
20. まとめ - ASP.NET Coreでは、Microsoft.AspNetCore.OpenApiパッケージと Microsoft.Extensions.ApiDescription.Serverパッケージを使用して、OpenAPIド キュメントの生成がサポートされている - ASP.NET Core Web API テンプレートからSwashbuckleが削除された - CIパイプラインと組み合わせるとAPIドキュメントの自動生成ができる
21. おまけ1：.httpファイル https://youtu.be/uKm1ho881gk?si=wsEPfTLOzlitHOI2
22. おまけ：.httpファイル https://youtu.be/uKm1ho881gk?si=wsEPfTLOzlitHOI2 @name を使用するとリクエスト結果を変数に格納できる
23. おまけ：.httpファイル @nameで定義した変数へのアクセス方法 The expression should adhere to the following pattern: {{requestName.(response|request).(body|headers).(*|JSONPath|XPath|Header Name)}}. https://youtu.be/uKm1ho881gk?si=wsEPfTLOzlitHOI2
24. ご清聴ありがとうございました。
25. References - https://learn.microsoft.com/ja-jp/aspnet/core/release-notes/aspnetcore-9.0?vie w=aspnetcore-9.0#openapi - https://learn.microsoft.com/ja-jp/aspnet/core/tutorials/getting-started-with-swa shbuckle?view=aspnetcore-7.0&tabs=visual-studio - https://devblogs.microsoft.com/dotnet/dotnet9-openapi/ - https://dev.to/eminvergil/an-alternative-to-swagger-in-dotnet-9-2jd6 - https://youtu.be/ooP0vkST3X8?si=vuotRdxOGkMx5X4T - https://learn.microsoft.com/ja-jp/aspnet/core/fundamentals/openapi/using-ope napi-documents?view=aspnetcore-9.0&WT.mc_id=%3Fwt.mc_id%3DDT-MV P-5004827#use-swagger-ui-for-local-ad-hoc-testing