Stoplight StudioでAPIドキュメント書く際に疑問に思ったこと

x-stoplight

Spotligh用の予約語

ステーブルIDという一意の識別子

公開ドキュメント時には表示されないらしい

他にも

x-deprecated

x-example

x-nullable

x-logo

などがあるみたい

これらはOAS2.0のサポートを拡張するために使われている

OAS2.0とは

OpenAPISpecificationVersion2.0の略

HTTP APIのインターフェースを定義するための仕様

OASに従ってAPIのインターフェースを記述することで人間とコンピュータ双方が理解できる

OASに則って定義されたAPIドキュメントは、OpenAPIドキュメントと呼ばれる。

yamlまたはJOSNで記述される。

つまり研修時に書いているAPI設計は、OpenAPIドキュメントであるということだ

OASではAPIのエンドポイントはPathsと呼ばれている

pathsはAPIが提供する全オペレーションが含まれる

PathsObject-エンドポイントの集合体

Path Item Object

getやputなどのこと

Operation Object

サマリーやレスポンス、リクエストボディを定義する

それぞれのフィールドを書く

tags - タグを定義して各エンドポイントに紐づけることで、エンドポイントをグルーピングできる

StoplightStudioやSwaggerのUI上で管理しやすくなる？

タグをつけると、プレビュー画面で見やすくなる

summary - エンドポイントの概要

operationId - 操作を識別するための一意の文字れる

Response Object

ステータスコードでの内容を定義する

descriptionが必須のフィールドらしい

contentフィールドが一番重要で、返却する内容を定義する

Swaggerが名前変わってOpenAPIになった

ヘッダー情報

Set-Cookie

HTTPクライアント(ブラウザ側)にサーバーの情報を確認する仕組み

基本的にログイン認証時のセッション情報保存に使われる

サーバーはSet-Cookieヘッダを用いて、Cookieをクライアントに送信する

クライアントは次回のサーバーアクセス時に、前回で受け取ったCookieをCookieヘッダに指定して送信する

Cookieには属性が用意されている。

語源の説は色々あるが

フォーチュンクッキーがしっくりきた

アメリカでの文化のメッセージの入ったお菓子

そもそもセッションとは

概念

通信の開始から終了までの一連の処理

仕組み

概念としてのセッションをHTTP上で実現させるための仕組み

HTTPは過去に起こった内容を記憶できない。

サーバーがクライアントに付与する目印をセッションID

やりとりの記録するものをセッションファイルという

クライアントがサーバーにリクエストを送信

サーバーはレスポンスの際、クライアントにセッションIDを付与。同時にセッションファイルをサーバー内に作成し、保存する

クライアントは２回目以降のリクエスト時、サーバーにセッションIDを提示する

サーバーは提示されたセッションIDに紐づくセッションファイルを確認

サーバーはセッションファイルを元に、前回の通信内容を反映したレスポンスを返す

Set-Cookieの属性

他にもあるよ！

secure

HTTPS/SSLプロトコルを使用しておこなわれた場合にのみ、サーバーに送信されることになる

HttpOnly

JSがクッキーにアクセスできないようにする

なので指定する場合、JSが操作したいものはローカスストレージに保存していくのが良さそうだ

HttpOnltyだとHTTPプロトコルでしか通信できないようにすると思ってしまったが、全く別なので注意。

Path

リクエストの URL に含む必要があるパスを示します

Set-Cookieは奥が深いので、フレームワークの機能に頼らず自分で考えられるようにしたい