• トップ
  • ブログ一覧
  • SwaggerでAPIドキュメントを作成する
  • SwaggerでAPIドキュメントを作成する

    たなゆー(エンジニア)たなゆー(エンジニア)
    2022.04.05

    IT技術

    Swaggerとは?

    SwaggerとはAPIのドキュメントを作成するためのツールです。

    公式説明によると「OpenAPI仕様に基づいて構築されたオープンソースツールセットでありREST APIの設計、作成、文書化に役立つツールです。」とのこと。

    SwaggerにはSwagger Editer、Sawgger UI、Swagger Codegenなど色々なツールがあります。

    今回はSwagger Editerというツールを使ってAPIのドキュメントを作成していきます。

    Swagger Editer

    Swagger Editerはブラウザでも使用できるSwaggerのファイル作成、編集ができるツールです。

    画面の左側にコード、右側にドキュメントの完成時ビューが表示されています。

    完成形を見ながらコードが書けるので非常に楽です。

    またブラウザで動かせるので使うための手間がかからないのも利点です。

    Swagger Editer の実際の画面

    Swagger Editer の実際の画面

    Swagger Editer で仕様書を作成してみる

    それでは実際にSwagger Editer で仕様書を作っていきたいと思います。作っていくといってもSwagger Editer を開くとサンプルのコードが既に書かれているのでそれを自分が作成するAPIに合わせて編集していく形になります。

    Swagger Editer では YAML または JSON 形式で書いていくことになりますが、標準ではYAMLで書いてあるので今回もYAMLで書いていきます。まずは基本的な形から見ていきましょう。

    サンプルのコードでは以下の10個のオブジェクトで構成されています。

    フィールド名内容
    swagger(必須)使用するswaggerのversion。
    info(必須)APIの概要。バージョンや内容の説明を書く。
    hostAPI通信を行うサーバーのホスト名。
    basePath上記のホスト以降のパス。 ”/” で描き始める。
    tagsタグの名前及びその説明。
    schemesAPIの通信プロトコル。基本的には"https"を記載。
    paths(必須)提供するAPIのパス。
    securityDefinitionsセキュリティ、認証の定義を記載。
    definitionsレスポンスやパラメータに使用するデータの定義。
    externalDocs外部リンクを定義するところ。

    swagger

    必須項目となっているswagger。ここには使用するswaggerのバージョンを記述します。

    特に理由がなければ標準の2.0のままでOKです。

    info

    infoも必須項目です。APIの概要を説明するためのものです。内容は下記の表参照。

    フィールド名内容
    descriptionAPIの概要を説明するところ。
    versionAPIのバージョンを説明するところ。
    titleAPIの名前、タイトル。
    contactAPIについての問い合わせ先を記入。
    termsOfService利用規約を記入。
    lisenceAPIのライセンス。

    host

    APIのホスト名を記入するところです。

    basePath

    hostに記入した部分以降のパスを記入します。

    Swagger Editer のサンプルコードでは host が petstore.swagger.io で basePath が /v2 となっているので

    APIのパスは http://petstore.swagger.io/v2/~のようになります。

    tags

    タグを定義するところです。

    ここで定義したtags と後述する paths を紐付けてタグ毎に各パスを表示してくれるようになっています。

    サンプルコードでは pet, store, user がtagsに該当し、それぞれの直下に書いてある部分がパスに該当します。

    schemes

    APIの通信プロトコルを記載する欄です。http, https, ws, wss の中から使用するプロトコルを記入してください。

    paths

    basePathに続くAPIのパスを記入する欄で、必須項目となっています。

    先ほど紹介したtags と紐づけて記入していくことでタグ毎にまとめられた見やすいドキュメントが作成されます。

    サンプルコードを例に記入方法を見ていきましょう。

    1paths:
    2 /pet/findByStatus:  #basePathに続くAPIのパス
    3    get:  #HTTP通信の種類
    4      tags:
    5      - "pet". #tagsで定義したタグを記入

    上記以外にもパラメーターやレスポンスを記入するフィールドもあります。

    securityDefinition

    セキュリティーに関する定義をここに記入します。

    definitions

    definitionsでは他の部分で使いまわしたい内容をオブジェクトで定義することができます。

    サンプルコードを一部抜粋したものも見ていきましょう。

    1paths:
    2  /pet:
    3    post:
    4#途中省略
    5 schema:
    6   $ref: "#/definitions/Pet"
    7definitions: 
    8 Pet:
    9    type: "object"
    10    required:
    11    - "name"
    12    - "photoUrls"
    13    properties:
    14      id:
    15        type: "integer"
    16        format: "int64"
    17      category:
    18        $ref: "#/definitions/Category"
    19      name:
    20        type: "string"
    21        example: "doggie"
    22      photoUrls:
    23        type: "array"
    24        xml:
    25          name: "photoUrl"
    26          wrapped: true
    27        items:
    28          type: "string"
    29      tags:
    30        type: "array"
    31        xml:
    32          name: "tag"
    33          wrapped: true
    34        items:
    35          $ref: "#/definitions/Tag"
    36      status:
    37        type: "string"
    38        description: "pet status in the store"
    39        enum:
    40        - "available"
    41        - "pending"
    42        - "sold"
    43    xml:
    44      name: "Pet"

    ここではpathのschemeの部分で $ref: を使用することでdefinitionsで定義した Pet の内容を流用しています。

    またdefinitionsで定義した内容はドキュメントにも Model という欄に記載されます。

    externalDocs

    ここでは外部リンクを定義します。

    クリックして欲しい文字と該当URLを記入することでリンクを作成することができます。

    終わりに

    Swagger Editer について見ていきました。これでAPIドキュメントの作り方がざっくり分かったかと思います。

    今回Swaggerで作成したAPIドキュメントをPDF化したいということもあるかと思います。

    その方法は次回書いていきたいと思いますので楽しみにしておいてください(笑)。

    たなゆー(エンジニア)

    たなゆー(エンジニア)

    おすすめ記事

    GitHubActionsのランナーに触れてみた

    こやまん(エンジニア)

    こやまん(エンジニア)

    2024.03.28

    IT技術

    Azure Data FactoryでSlackへ通知をしてみる

    たかやん(エンジニア)

    たかやん(エンジニア)

    2024.03.28

    IT技術

    GCP Secret Managerを使ってみた

    たなゆー(エンジニア)

    たなゆー(エンジニア)

    2024.03.21

    IT技術

    Bitriseのパイプラインと環境変数

    加納(エンジニア)

    加納(エンジニア)

    2024.03.11

    IT技術