swaggerhubを使ってAPI作成後、公開まで

#概要

swaggerhubを使ってAPI設計しつつ実装し、公開までが非常に便利だったので、少しはまった点など忘れないように一通り記載しておきます。

使用したツールはswaggerhubとswagger inspectorの二つです。swaggerhubでyaml形式もしくはjson形式でAPIの設計が可能です。swagger inspectorはAPIのテストに利用しました。swaggerhubでもテストは可能ですが、より詳細にパラメーターを操作したり、ログが記録されるので、何回も同様のクエリを送信する場合などにはswagger inspectorの方が便利です。

https://swagger.io/tools/swaggerhub/

https://inspector.swagger.io/builder

#OpenAPI
swaggerhubではswagger2.0とswagger3.0(OpenAPI 3.0)で記述することが可能で、新規で作成する場合はswagger3.0を選択しましょう。記述の仕方が少し違うようです。

API仕様書書くならswagger v2.0からv3.0に変更する際のポイント
https://qiita.com/shunichi_com/items/e63114f8d67beba14bfd

#githubと連携
swaggerhubで編集ボタンを押すと自動でgithubにプッシュすることができます。編集ログとして後程確認するなど便利なことが多いので連携することをお勧めします。

githubで先にリポジトリを作成、https://github.com/settings/tokensのPersonal access tokensでaccesstokenを作成します。（作成時、repo関係の権限は有効にしておきます。）

その後、swaggerhubで右上の設定ボタンをクリック→「Edit Github Push」をクリック、access token及びリポジトリなどの項目を入力し、「SAVE」を押します。

その後、ファイルを編集後、上部にある「SAVE」ボタンを押すと自動でプッシュされます！

#componentsを使おう
components機能を使い回すことが可能です。componentsを使うと記述量が減りますし、APIのSchemaとして登録されるのでAPI利用者によりわかりやすく表記されます。

api.yaml

components:
  schemas:
    Messages:
      type: object
      properties:
        messages:
          type: array
          items:
            type: string
          example:
            - "success"

#allOfとOneof
allOfとOneofという記述の仕方があり、使用すると大変便利です。componentsを作成し、それを合わせたり、選択肢を表記する時に使用します。

allOfはスキーマを合わせるときに使用します。下記の例はMessagesのcomponentとWebhooksのcomponentを合わせるという意味になります。

allOf:
    - $ref: '#/components/schemas/Messages'
    - $ref: '#/components/schemas/Webhooks'

oneOfはどちらかが適用されるという意味で、選択肢を表したい時に便利です。

oneOf:
    - $ref: '#/components/schemas/Cat'
    - $ref: '#/components/schemas/Dog'

公式に詳しい説明が載っています！
https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/

#API公開
APIを公開する時は、自サービスにそのAPIドキュメントを載せたりすると思いますが、swaggerhubで自動でドキュメントを作成され、そのまま自サービスのホームページにhtmlを張り付けることが可能です。また、右上の「View Documentation」をクリックすると、いい感じのAPIドキュメントページを閲覧することができます。

「try it out」の機能を使うとそのAPIのテスト送信をすることもできます！