views4GCPのストレージサービスについてまとめてみた。Exp:2516プチジロリアンで肉大好きなものです。頑張って執筆するクマ!!!TweetShareHatena拝啓、この記事を読みに来た皆様へ。V3を構成する各要素の説明を乗せた記事が無いことに挫折した僕が、英語で出来ている公式ドキュメントを見ながら書いた記事となります。V3の構成要素を知りたい!!と言う方のお役に立てれば!!!めちゃくちゃ嬉しいです!!!!追伸この記事は要素の説明や制限事項などが書いており、OpenAPIの書き方に関する記事ではありません。́ڡ`๑)では、始まります。ApigeeのSpecでOpenAPIを利用し、Proxy生成!Apigee&OpenAPIでAPIドキュメント作成が簡単になる!以前、この二つの記事を通してOpenAPIの使い道を確認して見ました。一から作り上げた物を使うのではなくサンプルを使って実施したため、物足りなさを感じながら記事を終わらせたので、今回は物作りのためにOpenAPIを解剖して中身をチェックします。基本的に使う要素だけを組んで実装するのは難しくないものですが、奥に入ると制約付き要素もあるので軽く見すぎると良くないと思います!!と!言うことなので、今回の流れは。OpenAPI解剖2ステップしかないから簡単そうに見えて実際は結構長い。目次1.解剖対象のOpenAPIバージョンは?2.OpenAPIの解剖準備3.OpenAPIの解剖オペ、開始3.1.はじめ、APIのメタデータから3.2.APIの通信先、サーバ情報3.3.APIで行われる操作の定義、パス3.4.再利用するための定義集、コンポーネント3.5.大事な認証処理、セキュリティー3.6.各操作をカテゴライズしよう、タグ3.7.最後は!?外部文書まとめ1.解剖対象のOpenAPIバージョンは?後々これを活用することになるApigeeのためにV2を見た方が良いと思いましたが、ちょっと古いバージョンなので最新のV3.0.2(2018.10.08にリリース)を解剖することにしました。’ApigeeはV2を支援すると言うのにV3で解剖したら使えないのでは?’と思いますが、V2に変換してくれるツールが存在するので、実際作業に取り込んだ時はそれを使って乗り越えて見ようと思います。準備するもの、その1OpenAPIを作成するファイルフォーマットを決める!!だけなので特に準備するものはありません。(この記事を通じて何か作るわけではないので、ファイルすらも必要ないのですが。OpenAPIの基礎知識として知っておこう!)OpenAPIはJSON又はYAML形式で作成可能で、お互いに変換もできますが、YAMLからJSONに変換するためには下記の制約付きでOpenAPIの作成を推奨しています。ベースとなるYAMLのバージョンは1.2JSONスキーマルールに記載されているタグを使用することYAMLマップに使用されるキーはYAMLフェイルセーフスキーマルールを元にスカラー文字列に制限する必要がある引用:公式ドキュメントからそれとファイルの格納先はプロジェクトのルートにopenapi.拡張子(json又はyaml)で保存することを推奨しているので、作業するときはこれに従いましょう。英字の大小文字を区別するため、フィールド名をちゃんと確認しましょう。働いてくれるので作業しやすくはなりますが、配列系のオブジェクトの中では自動補完が働かない(例:Parametersオブジェクト)のとSecurityやExamplesオブジェクトの中でも自動補完が働かないので自動補完は万能ではありません。フィールド名が固定されている要素以外に自由記載可能な要素も存在します。OpenAPIの中身は下記の要素で構成されています。OpenAPIのバージョン情報:openapiAPIの詳細情報:info接続先の情報:serversエンドポイント:paths再利用できるオブジェクト集:components認証はこちら:securityカテゴリ化するためには必須:tags外部文書リンクを追加しよう:externalDocs上から順番に何でできているのか、確認しながら進みましょう。3.1.はじめ、APIのメタデータから使用するOpenAPIのバージョンや、APIに関する情報を記述します。OpenAPIを利用するツール上で必要な要素がなければ最低限の定義をしてもOKです。接続対象となるターゲットサーバ集。配列であるため、複数のサーバを追加することができますが、このオブジェクト自体は必須ではないため、必ず作成する必要はありません。変数の説明3.3.APIで行われる操作の定義、パスここがこのOpenAPIの核心部となるところです。各パスに対してgetやputなどの操作を定義し、それぞれの操作に対してリクエストやレスポンスの定義もここで行われます。パス内部で使用可能なパラメーターのリストオブジェクトの詳細は別途の表で説明パスオブジェクトを構成する要素の中で、OperationとParametersオブジェクトはサイズが大きいため別途、表で解剖します。出現頻度が高いパラメータオブジェクトから。3.3.1.Parametersオブジェクトパラメータを定義する上で一番重要なものはどの場所にどんなパラメータ名で保存されているのかです。パスパラメータなのか、ヘッダーに保存されているのかなどを明確にしないといけませんね。inがqueryの場合に有効で空の値を渡すことができるようになるstyleが指定され直列化できない値の場合これは無視されるこの要素は削除予定なので使用するのは非推奨パラメータを直列化(シリアルライズ)をするためには下記の項目が必要です。リテラルで参照可能な外部文書のURLより複雑な構造を持つパラメータを指定するのであればコンテンツを使うと良いでしょう。Schemaオブジェクトで指定したパラメータのオブジェクト形式を定義する、詳細はこちら3.3.2.OperationオブジェクトHTTPメソッドの定義を行います。ここではフィールドがどこの配下に位置するのかを明確にするため、postメソッドだと仮定してフィールド名を記載しました。操作内部で使用可能な代替サーバ情報パスオブジェクト直下に定義されているServerオブジェクトをオーバーライドする構成は3.2を参照Responsesオブジェクト※ステータスコードは’200’を仮定してフィールド名を記載します。ターゲットサーバを定義3.4.再利用するための定義集、コンポーネントReferenceオブジェクトが参照するオブジェクトをここで定義します。オブジェクト定義後、参照可能なオブジェクトは九つ存在!schemasresponsesparametersexamplesrequestBodiesheaderssecuritySchemeslinkscallbacks詳細はこちらを参照、どう言う形で実装をするのかを参考にすると良いです。認証が必要な場合はこのオブジェクトが必要になりますが、作り方が他のオブジェクトちょっと違います。“productList”]})セキュリティーオブジェクトはコンポーネントのセキュリティースキームを参照する様になってます。中身を確認するにはセキュリティースキームを解剖しないといけません。openIdConnect”限定OAuth2設定値を検出するためのURL3.6.各操作をカテゴライズしよう、タグタグは各Operationオブジェクトの内部で定義しても良いが、一足先にAPI全体に反映されるタグを定義することも可能です。操作内部で定義する全てのタグをここで定義してあげる必要はないので、基本的なものだけ定義するのも良いと思います。このタグに関する外部資料を追加3.7.最後は!?外部文書ここではAPI文書全体に関する外部資料を追加しましょう。構成は3.3.2のexternalDocsを参照まとめ苦手な英語でできている文書を見ながら理解しようとしたので、かなり難しい作業となりました。V3を理解するにあたって役に立つものになると嬉しいです!まず最初の一歩として中身の確認を行い、次は物作りに入ろうと思います。OpenAPI作成、基本構造を作る編。