Tweet
Tweet

Slide 1

Slide 1 text

API Night API Night Sapporo 2024 Sapporo 2024 @ E CROSS PARK Sapporo 2024 Postman #APINight - - What do you use for API documentation?

Slide 2

Slide 2 text

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 - -

Slide 3

Slide 3 text

Sapporo 2024 Postman #APINight - -

Slide 4

Slide 4 text

Sapporo 2024 Postman #APINight - - API Gateway AWS Cloud Amplify Hosting Amplify Backend AppSync DynamoDB Lambda Step Functions Momento Cache

Slide 5

Slide 5 text

Sapporo 2024 Postman #APINight - - Amazon API Gateway

Slide 6

Slide 6 text

Sapporo 2024 Postman #APINight - - Amazon API Gateway (HTTP) ここだけ手動デプロイでドキュメント化もサボって早3年。。 そろそろちゃんとするために、各種ツールを調査した結果のアウトプット。 ゼロベースの調査結果なので、やさしいツッコミをお願いします！笑

Slide 7

Slide 7 text

Sapporo 2024 Postman #APINight - - アンケートやってます

Slide 8

Slide 8 text

Sapporo 2024 Postman #APINight - - REST HTTP AWS コンソール

Slide 9

Slide 9 text

Sapporo 2024 Postman #APINight - - REST HTTP AWS コンソール

Slide 10

Slide 10 text

Sapporo 2024 Postman #APINight - -

Slide 11

Slide 11 text

Sapporo 2024 Postman #APINight - - あんまり、見やすくないですね... そして、HTTP API は対応していない

Slide 12

Slide 12 text

Sapporo 2024 Postman #APINight - - HTTP API エクスポートは出来そう

Slide 13

Slide 13 text

{ 　"openapi" : "3.0.1", 　"info" : { 　　"title" : "bff-dev", 　　"description" : "[hod]202202 HTTP API 開発用", 　　"version" : "2022-01-24 08:36:39UTC" }, Sapporo 2024 Postman #APINight - - ダウンロードしてきた

Slide 14

Slide 14 text

{ 　"openapi" : "3.0.1", 　"info" : { 　　"title" : "bff-dev", 　　"description" : "[hod]202202 HTTP API 開発用", 　　"version" : "2022-01-24 08:36:39UTC" }, Sapporo 2024 Postman #APINight - - ダウンロードしてきた

Slide 15

Slide 15 text

Sapporo 2024 Postman #APINight - - 「"openapi" : "3.0.1"」で検索

Slide 16

Slide 16 text

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.

Slide 17

Slide 17 text

Sapporo 2024 Postman #APINight - - What is the OpenAPI Specification? OpenAPI仕様（OAS）は、HTTP APIのための、プログラミング言語にとらわれない標準的 なインターフェイス記述を定義しています。これにより、人間とコンピュータの両方が、ソ ースコードへのアクセスや追加ドキュメント、ネットワークトラフィックの検査を必要とせ ずに、サービスの機能を発見し理解することができます。OpenAPIによって適切に定義され れば、コンシューマは最小限の実装ロジックでリモートサービスを理解し、対話することが できます。OpenAPI仕様は、インターフェイス記述が低レベルのプログラミングのために行 ってきたことと同様に、サービスを呼び出す際の当て推量を取り除きます。 https://spec.openapis.org/oas/latest.html

Slide 18

Slide 18 text

Sapporo 2024 Postman #APINight - - OAS 調べてみた OpenAPI Specification の 略称。 REST API の記述フォーマット。 かつては、Swagger Specification って呼ばれていたが、Linux foundation のオープンソース共同プロジェクトである OpenAPI Initiative が統括して いる。このとき、名称が変わり、OpenAPI Specification へ。 現時点において、2021年に出た v3.1.0 が最新版

Slide 19

Slide 19 text

Sapporo 2024 Postman #APINight - - OAS 調べてみた OpenAPI Specification の 略称。 REST API の記述フォーマット。 かつては、Swagger Specification って呼ばれていたが、Linux foundation のオープンソース共同プロジェクトである OpenAPI Initiative が統括して いる。このとき、名称が変わり、OpenAPI Specification へ。 現時点において、2021年に出た v3.1.0 が最新版

Slide 20

Slide 20 text

Sapporo 2024 Postman #APINight - - v3.1.0 が最新版

Slide 21

Slide 21 text

Sapporo 2024 Postman #APINight - - あーね

Slide 22

Slide 22 text

Sapporo 2024 Postman #APINight - - あーね 一旦、後回し （誰か教えてぇ）

Slide 23

Slide 23 text

今回 試したもの AWS コンソール Postman Sapporo 2024 Postman #APINight - - Swagger UI

Slide 24

Slide 24 text

今回 試したもの その1 AWS コンソール Sapporo 2024 Postman #APINight - -

Slide 25

Slide 25 text

Sapporo 2024 Postman #APINight - -

Slide 26

Slide 26 text

今回 試したもの AWS コンソール Postman Sapporo 2024 Postman #APINight - - Swagger UI

Slide 27

Slide 27 text

今回 試したもの その2 Swagger UI Sapporo 2024 Postman #APINight - -

Slide 28

Slide 28 text

Swagger UI - - yaml API Gateway GitHub Amplify

Slide 29

Slide 29 text

Swagger UI - - それっぽいのが出てきた

Slide 30

Slide 30 text

Swagger UI - - DEMO

Slide 31

Slide 31 text

今回 試したもの AWS コンソール Postman Sapporo 2024 Postman #APINight - - Swagger UI

Slide 32

Slide 32 text

今回 試したもの その3 Postman Sapporo 2024 Postman #APINight - -

Slide 33

Slide 33 text

Postman - - yaml

Slide 34

Slide 34 text

Postman - -

Slide 35

Slide 35 text

Postman - -

Slide 36

Slide 36 text

Postman - -

Slide 37

Slide 37 text

Postman - - DEMO

Slide 38

Slide 38 text

Sapporo 2024 Postman #APINight - - よさそう

Slide 39

Slide 39 text

Sapporo 2024 Postman #APINight - - 全体で気になるところ v3.0.1 と v3.1.0 の違いは？ AWS側追従してない？ これってデメリットある？ AWS専用の項目とかあるっぽい？ CI/CDに組み込むためには ドキュメントのために時間を割くのは現状のチーム状況だと厳しい CI/CD の中に組み込みたい また、テストしてたら追記したくなるはずなので、そっちのルート も考えたい GraphQL も使ってるけど、OASって、対応してるのかしら

Slide 40

Slide 40 text

Sapporo 2024 Postman #APINight - - まとめ AWS コンソール ちょっとイマイチ。そもそもHTTP対応していない Swagger UI 見た目は好き！拡張はプラグインとかあるらしい Postaman 統合されてる感じが最高。変更もできるのいい。 テスト書いてくれるの期待

Slide 41

Slide 41 text

Sapporo 2024 Postman #APINight - - Swagger UI 58.3% Postaman 16.7% ドキュメント無し 16.7% エクセル/スプシ 8.3%

Slide 42

Slide 42 text

API Night API Night Sapporo 2024 Sapporo 2024 @ E CROSS PARK Sapporo 2024 Postman #APINight - - Thank you !!