OpenAPIを理解しよう、基礎編 – OpenAPI、Apigeeに立つ

OpenAPIの理解を深めるために作成した前回の記事で予告した基本構造作りをします。
最初から色んな事をやり過ぎると混乱に落ちる可能性があるので、パラメータに設定したテキストを編集して返すAPIを呼び出す処理を実装する事にしました！
APIの実装やOpenAPIドキュメント作成のみではなく、OpenAPIの変換や動作確認も必要なので、ゆっくり進みましょう。

今回の流れは？

1. バックの処理を実装、シンプルにGCPのCloud Functionsで実装
2. OpenAPI V3ドキュメント作成
3. OpenAPI V3ドキュメントをOpenAPI V2ドキュメントに変換
4. 変換したV2ドキュメントを確認&修正（修正は必要な場合）
5. V2ドキュメントを持ってApigeeでSpec及びProxiesの生成
6. 最後の動作確認

今回はステップが多く、あれこれやって行きます。

0.事前準備、必要なものは？

順番に実施しながら用意すればいいので、事前に準備するものはありません。
記事を読みながら一つずつ整えて行きましょう！

1.まずはバックエンド処理を用意する

OpenAPIドキュメント作成より先に叩く対象を準備します。APIを作りましょう。
Cloud Functionsでnode8ベースのJSを実装します。
（もしくは同じ処理ができるものを構築してもOKです。）

1.1.GCPから関数を作成するには？

GCPコンソールのメニューからCloud Functionsを選択します。

‘関数を作成’ボタン押下

表示される項目の中から名前のみ変えました。
他の項目は修正する必要がないので、初期値のままでOKです。

index.jsに書いてあるスクリプトを下記の内容に修正します。

// Queryパラメータに設定されているinputTextの有無で、編集内容が変わる
let message = 'Hello, ' + (req.query.inputText || 'World') + '?';

// CORS対応
res.header('Access-Control-Allow-Origin', "*");
res.header('Access-Control-Allow-Headers', "Origin, X-Requested-With, Content-Type, Accept");

修正後のコード

修正が終わったので画面の下にある’作成’ボタンを押下し関数を作成します。

少し待つと作成が終わります。

問題なく作成されたので関数をクリックし、動作確認をしましょう

1.2.関数、始動！

関数名をクリックすると関数の詳細情報が表示されます。
そこからトリガータブをクリックし、画面に表示されたURLをクリックします。

「Hello, World?」が表示されましたか？そうであればバックエンドは準備完了です。
パラメータが存在する場合、パラメータと結合されたテキストが返されるので、今はWorldが結合された形態のテキストがリターンされます。

パラメータ設定時

では次の段階へ〜

2.ここが作業の本番、OpenAPIドキュメント作成

上の工程で作成したバックエンドを呼び出すOpenAPIドキュメントを作成する番です！
ドキュメントに入る要素話は前回の記事を参考に、どんな要素が定義されるのか理解しながら進みましょう。
※OpenAPI V3を作成するのでV2を支援するApigeeでは変換せずに使用する事は不可能です

2.1.最強の道具！？その名はSwagger Editor

Swagger Editorはウェブブラウザ上でOpenAPIドキュメント作成が可能で、作業し易い環境を提供します。
別途のプログラムインストールや会員加入などが不要なので、楽に作業開始ができます。

まずはhttps://editor.swagger.io/に入りましょう、サンプルのドキュメントが表示されます。

サンプルとは言え動作するものなので、少し叩いて見るのも良いです。
ここで、僕らが作業する場所は左側にあるエディターです。

作成準備ができたので、エディターの内容を下記のものに入れ替えてください。
YAML形式で作成したシンプルで分かり易い要素のみで詰め込んだ、OpenAPIドキュメントとなります。
あ、Serverオブジェクトの中身を自分の環境に合わせて修正する事を忘れないでください〜！
下記の内容は僕の環境に合わせた作例として載せましたので、サーバの向き先修正を必ず！実施すること！！

※1.OpenAPIドキュメント作成時、各要素を一つずつ追加する事でどう変化するかを確認することをお勧め！目で見ることで理解が深まります。
※2.各要素の説明は行いませんので、前回の記事を参考にしてください。

openapi: 3.0.2
info:
  title: Hello World
  description: what's your name? speak to!
  termsOfService: https://policies.google.com/terms?hl=ja&gl=JP
  contact:
    name: Cloud Ace Technical Blog
    url: https://www.apps-gcp.com/
    email: test@apps-gcp.com
  license:
    name: license by Open Source Initiative
    url: https://opensource.jp/osd/osd-japanese.html
  version: '1.0'
servers:
  - url: 'https://us-central1-{projectName}.cloudfunctions.net' ← 自分が構築した環境のものに修正、下のServer変数は使い方の例として入れたものなので消してもOK
    description: Step1, call API
    variables:
      projectName:
        enum:
          - ca-iwans-test
          - google-test
        default: ca-iwans-test
        description: set project
paths:
  /Hello-OpenAPI:
    summary: Hello, XXXX?
    description: this api, combine to Hello world and parameter text
    get:
      summary: return combine text
      description: Hello, + parameter.text + ?
      externalDocs:
        url: https://www.apps-gcp.com/openapi_understanding_dissection/
        description: previous post
      operationId: combineText
      parameters: 
        - name: inputText
          in: query
          description: user input
          required: false
          deprecated: true
          allowEmptyValue: true
          schema:
            type: string
      responses:
        default:
          description: return to api response
          content:
            text/plain:
              schema:
                type: string
      deprecated: false

上記の内容に入れ替えるとエディターの右側にサーバの選択（サーバ変数の値変更も）や実行するAPIに関する情報などが表示されますので、問題なく動くのか試して見ましょう。

本当は作例からサーバ情報のみを修正してそれをYAMLに保存するだけで良いのですが、OpenAPIドキュメントを作成しながら動作確認をする方法を覚えておく必要があったので、Swagger Editorを使用しました。

2.2.作成したものを保存して見よう

エディターのメニューから保存できます。


公式ドキュメントから推奨されるファイル名で保存される又は保存しようとするので、なぜ推奨されるのか詳しい内容は記載されてないのですが、それらしい理由があると信じて！ファイルを保存しましょう。

動作確認も終えた事だし、保存もできたし、Apigeeで活用できる形にしないと行けませんね、変換しましょう！

3.V3 → V2、ドキュメントバージョン落とし！

最新バージョンに適応する為にOpenAPIドキュメントは最新のV3で作成していますが、これだとApigeeでは使い物になりません。

3.1.変換どうしよう？

APIMATICを利用すればV3をV2に変換できます。
加入しないといけないので、少し工程が長くなりますが、このサイトを知っておくと何かしら役に立ちそうなので、体験する事にしました。
※このサービスは有料ですがタイムトライアルでお試しできる期間があります
トライアル後の使用には注意しましょう（プラン加入が必要）

ステップ１. Sign up! 加入する

ステップ２. Log in! 接続せよ

ステップ３. ログイン後に表示される画面からトランスフォームAPIをクリック

ステップ４. Choose file押下後、変換対象のYAMLファイルを選択

ステップ５. ファイルが設定されている事を確認、Export FormatからOpenAPI/Swagger V2.0 (YAML)を選択後、Convertボタン押下

ステップ６. 変換対象のファイルチェック後、お知らせが表示されます
エラーや注意事項などがあればそれの対応が必要になるので無視せず、内容確認後Proceedを押してください
今回の場合、テストケースが生成されたことと一部の要素に説明フィールドが存在しないと言うメッセージだけなので次へ進みましょう（APIMATICに何かを構築しているわけではないので、テストケースの話がなんで出たのか分かりません）

変換に成功しました！

変換後のファイル名にはSwaggerYamlが含まれているので、怪しいものだと疑わないように！！

これでファイルの変換は完了しましたが、OpenAPIドキュメントの仕様上、要素の有無や要素名が違うものとかもありえるので、変換したものの内容チェックが必要です。

4.変換したV2ドキュメントの確認

変換は成功で、動作確認もちゃんと取れると思いますが、変換結果物をよく見ると何かが足りないところが出てくると思います。
変換するんだとしても漏れ無くV3の要素をV2に引っ張ってくるものではないようで。。
では、これからOpenAPI V2の要素を探りながら進めましょう。

4.1.メタデータの違い

V3のメタデータはopenapiとinfoオブジェクトで構成されています。
V2の場合、infoオブジェクトはV3と同じなので、openapiの代わりの要素に注意する必要があります。
V2のメタデータは下記の通り

変換されたソースを見ましょう

swagger: '2.0'
info:
  version: '1.0'
  title: Hello World
  description: what's your name? speak to!
  contact:
    email: test@apps-gcp.com
    name: Cloud Ace Technical Blog
    url: https://www.apps-gcp.com/
# 追加部分_Start
  termsOfService: https://policies.google.com/terms?hl=ja&gl=JP
  license:
    name: license by Open Source Initiative
    url: https://opensource.jp/osd/osd-japanese.html
# 追加部分_End

termsOfServiceとlicenseオブジェクトが欠落されていたので、追加しました。
それ以外はちゃんと変換されましたね。

4.2.構成が全然違うサーバ情報

V3は一つのオブジェクトの中に定義されるものが、V2だとバラバラに。。なのでちょいと厄介なものになりました。
V2のサーバ情報は下記の通り

変換されたソースを見ましょう

host: us-central1-ca-iwans-test.cloudfunctions.net
basePath: /
schemes:
- https
consumes:
- application/json
produces:
- application/json

V2でのサーバ情報は上のソースをベースに説明すると、
hostにホストアドレスを記載→basePathにホストアドレスからエンドポイントまでの経路を記載→schemesにプロトコルを記載する流れで完成されます。
consumes、producesは伝送＆受信されるデータタイプを指定します。

V3との一番大きい差は！サーバ変数が使用不可と言うことです！！
なので、アドレス指定は常に一つしかできません。

4.3.パスとメソッド

V3と比べて見ると一部の要素が存在しません
概要、説明、サーバ情報、そしてHTTPメソッドの内 ‘trace’ を使えないので注意

V2のパスオブジェクトは下記の通り

前回の記事と同じくパラメータから確認します。

4.3.1.Parametersオブジェクト

V3と同じ要素は一部のみ、他の構成が違うので確認しておく必要があります。

inがbodyの場合

inがbodyではない場合

4.3.2.Operationオブジェクト

このオブジェクトの構成はV3がV2をベースに追加要素を入れたものなので、
ここではV3にあってV2にない要素、V3と内容が違う要素を説明します。
※postメソッドだと仮定してフィールド名を記載します

Responsesオブジェクト
ここはV3と比べ構成要素が半分違うので、一つ一つチェックしながら行きます。
※ステータスコードは’200’を仮定してフィールド名を記載します

変換されたソースを見ましょう

paths:
  /Hello-OpenAPI:
    get:
      description: Hello, + parameter.text + ?
      summary: return combine text  #値が違ったので、修正
      operationId: combineText      #自動生成された値だったので、修正、
      deprecated: false
      produces:
      - text/plain
      parameters:
      - name: inputText
        in: query
        required: false
        allowEmptyValue: true       #削除されていたので、追加
        type: string
        description: user input
      responses:
        200:
          description: return to api response
          schema:
            type: string
          headers: {}
      externalDocs:
        url: https://www.apps-gcp.com/openapi_understanding_dissection/
        description: previous post
# 削除対象_Start
definitions:
  projectName:
    title: projectName
    example: ca-iwans-test
    type: string
    enum:
    - ca-iwans-test
    - google-test
tags: []
# 削除対象_End

返還後の品質チェック、下記の修正を行いました。

1. オペレーションオブジェクトの中身を良く見るとsummaryとoperationIdが変わっていたので、V3の内容を元に修正
2. パラメータの設定、deprecatedはV2に存在しない要素だから大丈夫なのですが、allowEmptyValueがなかったので追加
3. どうやらサーバ情報に記載したサーバ変数がdefinitionsに入ってます。
   だけどdefinitionsとtagsは不要なので、削除しましょう。

変換したV2ドキュメントのチェックが終わりました！長かったあ。。。
若干の修正が発生するもののこれぐらいの修正ならばV3でできている文書をV2に変換する作業に役立つものだと思います。

変換＆修正後に異常がないことをSwagger Editorで動作確認をした後はApigeeに突入！！

5.ApigeeでSpec及びProxiesの生成

なんとかOpenAPI V3からV2への変換が成功したので、これを活用する番です。

5.1.OpenAPIドキュメント取り込み、Spec作成

Apigee Edgeにログインし、下記の順番で操作します。
① 左のメニューから’Spec’を選択
② ‘+Spec’ → ‘Import file’を選択

忘れずに変換前ではなく変換後のものを選択してください。

Import完了！リストに新しく追加したSpecが見えます。
ファイル名によってSpec名が決まるので、もし変えた場合、変えた名前が表示されます。
でも、これはファイル名と違いますね？なんだろう。。中身の確認をしましょう。

生成したSpecの中身を見る限り変換したもので間違いないようです。
お試しでImportしたSpecの動作確認を取りました。（実施方法はSwagger Editorと同一）

問題ないことを確認したのでプロキシ生成へ移ります。

5.2.Specからのプロキシ生成も簡単にできます

APIを構築するにはプロキシの生成が必要なので、ここ！を参考に実施してください。
Specの選択に間違いがないように注意！
※上記の流れを実施中にSpec選択後、’Internal Server Error’が発生した場合は下記の手順で乗り越えましょう。
（OpenAPIドキュメントからSpecを生成し、生成したSpecからプロキシを作ろうとすると’Internal Server Error’でプロキシが生成できないバグがあります。ここを参照）

既存のSpecは忘れ（バグの影響でプロキシ生成に使えない）再アップロードを実施します。
どうやらここからアップして実施するものには問題がないようです。。
① 上記のリンク先の流れだと’My Specs’タブから選ぶのですが、バグ回避のため’Upload file’から接近します
② ここをクリックし、OpenAPIドキュメントを選びましょう（Spec生成で使用したもの）
③ ファイルが設定されましたので、下の’Select’ボタンを押下

正常に処理された場合、下記のようなアドレスが表示されます

万が一！の場合もあるので、ファイル名を変えてSpec生成からやり直して見ました。
変換したドキュメントを下記の名前に修正。

Spec生成完了、今回は正しい名前で生成されました。
どうやら前回の生成ではファイル名に’.yaml’が入っていて途中で切れたようです。

新しく生成したSpecで、プロキシを作成して見ましょう！

あ、ダメだ。。。。
プロキシ生成段階でアップロードしてやるしかないようです。
こんなの初めてだ！！

Specの選択で問題が発生したものの回避策があって助かりました。。
続きの作業を実施し、プロキシの生成を完了しましょう。

ここまで来たのであれば？

最後の確認のみ

6.最後の動作確認

画面の操作やAPI実行手順などここだと省略されているものがあるので、ここを一回ご覧になってください。

まずは実施前のチェックポイント一つ！
プロキシリスト画面で、環境が’test’になっていることを確認してください。
プロキシ生成手順通りに進んだのであれば、稼働中のものはここにあります。

ステータス欄がキャプチャーの通り緑色であればOKです。

Apigee Edgeで今回生成したプロキシをトレースして、ちゃんとやり取りを行っているかを確認します。
https://apigee-restclient.appspot.com/ このRestクライアントを利用し、プロキシのアドレス＋エンドポイント名（今回の作業で指定した’Hello-OpenAPI’）の組み合わせでURLを埋めてから’Send’ボタンを押下すると終わりです。

レスポンスの結果が表示されました！
クエリパラメータの設定をしてないため、Hello World?が表示されましたね。

続いてトレースの記録を確認しましょう。
結果を見る限り正しく正常終了した事が分かります。

クエリパラメータを追加してもう一回実行しました。
入力した値が結合された状態でレスポンスが戻ってきましたか？

トレースからも正常終了した事とレスポンス内容に間違いがない事が確認できました。

これで基本編終了となります！

まとめ

OpenAPIドキュメントを作成するために最初からV3ではなくV2で実装すれば楽になりそうですが、V2は古いのでV3を中心に勉強しておきたい気持ちでした。
その影響で少し厄介な中間過程が追加され、変換したり問題は無いか確認したりしましたけど、V3と同時にV2も把握して行く事になるので無駄にはならないと思います。
（内容は重くなりましたが；）

前回のV3解剖記事と同様にV2もドキュメントとの戦いだったので、頭痛い作業ではありましたが基本構造作りが出来て’どう作れば良い？’かの謎が解明された気がします。
この記事で扱った要素以外のものは次回の課題として残しておきます！

ではまた〜！
（あ。。。APIMATICどうしようか。。。）