APIのドキュメント化何使ってますか？

手動でポチポチ作った古のAmazon API Gateway のドキュメント化をいろいろ試してみました。皆さんが使ってる環境も教えてください！

#APINight
https://postman.connpass.com/event/317161/

Transcript

1. API Night API Night Sapporo 2024 Sapporo 2024 @ E CROSS PARK Sapporo 2024 Postman #APINight - - What do you use for API documentation?
2. AWS Community Hero AWS User Group Leader AWS Samurai 2019 JAWS-UG Sapporo Committee Media-JAWS Committee Kazuki Miura Working at Sapporo 2024 Postman #APINight - -
3. Sapporo 2024 Postman #APINight - -
4. Sapporo 2024 Postman #APINight - - API Gateway AWS Cloud Amplify Hosting Amplify Backend AppSync DynamoDB Lambda Step Functions Momento Cache
5. Sapporo 2024 Postman #APINight - - Amazon API Gateway
6. Sapporo 2024 Postman #APINight - - Amazon API Gateway (HTTP) ここだけ手動デプロイでドキュメント化もサボって早3年。。 そろそろちゃんとするために、各種ツールを調査した結果のアウトプット。 ゼロベースの調査結果なので、やさしいツッコミをお願いします！笑
7. Sapporo 2024 Postman #APINight - - アンケートやってます
8. Sapporo 2024 Postman #APINight - - REST HTTP AWS コンソール
9. Sapporo 2024 Postman #APINight - - REST HTTP AWS コンソール
10. Sapporo 2024 Postman #APINight - -
11. Sapporo 2024 Postman #APINight - - あんまり、見やすくないですね... そして、HTTP API は対応していない
12. Sapporo 2024 Postman #APINight - - HTTP API エクスポートは出来そう
13. { 　"openapi" : "3.0.1", 　"info" : { 　　"title" : "bff-dev", 　　"description" : "[hod]202202 HTTP API 開発用", 　　"version" : "2022-01-24 08:36:39UTC" }, Sapporo 2024 Postman #APINight - - ダウンロードしてきた
14. { 　"openapi" : "3.0.1", 　"info" : { 　　"title" : "bff-dev", 　　"description" : "[hod]202202 HTTP API 開発用", 　　"version" : "2022-01-24 08:36:39UTC" }, Sapporo 2024 Postman #APINight - - ダウンロードしてきた
15. Sapporo 2024 Postman #APINight - - 「"openapi" : "3.0.1"」で検索
16. Sapporo 2024 Postman #APINight - - What is the OpenAPI Specification? The OpenAPI Specification (OAS) defines a standard, programming language- agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.
17. Sapporo 2024 Postman #APINight - - What is the OpenAPI Specification? OpenAPI仕様（OAS）は、HTTP APIのための、プログラミング言語にとらわれない標準的 なインターフェイス記述を定義しています。これにより、人間とコンピュータの両方が、ソ ースコードへのアクセスや追加ドキュメント、ネットワークトラフィックの検査を必要とせ ずに、サービスの機能を発見し理解することができます。OpenAPIによって適切に定義され れば、コンシューマは最小限の実装ロジックでリモートサービスを理解し、対話することが できます。OpenAPI仕様は、インターフェイス記述が低レベルのプログラミングのために行 ってきたことと同様に、サービスを呼び出す際の当て推量を取り除きます。 https://spec.openapis.org/oas/latest.html
18. Sapporo 2024 Postman #APINight - - OAS 調べてみた OpenAPI Specification の 略称。 REST API の記述フォーマット。 かつては、Swagger Specification って呼ばれていたが、Linux foundation のオープンソース共同プロジェクトである OpenAPI Initiative が統括して いる。このとき、名称が変わり、OpenAPI Specification へ。 現時点において、2021年に出た v3.1.0 が最新版
19. Sapporo 2024 Postman #APINight - - OAS 調べてみた OpenAPI Specification の 略称。 REST API の記述フォーマット。 かつては、Swagger Specification って呼ばれていたが、Linux foundation のオープンソース共同プロジェクトである OpenAPI Initiative が統括して いる。このとき、名称が変わり、OpenAPI Specification へ。 現時点において、2021年に出た v3.1.0 が最新版
20. Sapporo 2024 Postman #APINight - - v3.1.0 が最新版
21. Sapporo 2024 Postman #APINight - - あーね
22. Sapporo 2024 Postman #APINight - - あーね 一旦、後回し （誰か教えてぇ）
23. 今回 試したもの AWS コンソール Postman Sapporo 2024 Postman #APINight - - Swagger UI
24. 今回 試したもの その1 AWS コンソール Sapporo 2024 Postman #APINight - -
25. Sapporo 2024 Postman #APINight - -
26. 今回 試したもの AWS コンソール Postman Sapporo 2024 Postman #APINight - - Swagger UI
27. 今回 試したもの その2 Swagger UI Sapporo 2024 Postman #APINight - -
28. Swagger UI - - yaml API Gateway GitHub Amplify
29. Swagger UI - - それっぽいのが出てきた
30. Swagger UI - - DEMO
31. 今回 試したもの AWS コンソール Postman Sapporo 2024 Postman #APINight - - Swagger UI
32. 今回 試したもの その3 Postman Sapporo 2024 Postman #APINight - -
33. Postman - - yaml
34. Postman - -
35. Postman - -
36. Postman - -
37. Postman - - DEMO
38. Sapporo 2024 Postman #APINight - - よさそう
39. Sapporo 2024 Postman #APINight - - 全体で気になるところ v3.0.1 と v3.1.0 の違いは？ AWS側追従してない？ これってデメリットある？ AWS専用の項目とかあるっぽい？ CI/CDに組み込むためには ドキュメントのために時間を割くのは現状のチーム状況だと厳しい CI/CD の中に組み込みたい また、テストしてたら追記したくなるはずなので、そっちのルート も考えたい GraphQL も使ってるけど、OASって、対応してるのかしら
40. Sapporo 2024 Postman #APINight - - まとめ AWS コンソール ちょっとイマイチ。そもそもHTTP対応していない Swagger UI 見た目は好き！拡張はプラグインとかあるらしい Postaman 統合されてる感じが最高。変更もできるのいい。 テスト書いてくれるの期待
41. Sapporo 2024 Postman #APINight - - Swagger UI 58.3% Postaman 16.7% ドキュメント無し 16.7% エクセル/スプシ 8.3%
42. API Night API Night Sapporo 2024 Sapporo 2024 @ E CROSS PARK Sapporo 2024 Postman #APINight - - Thank you !!