【Swagger】API設計書をSwaggerで管理する

19229 ワード
swagger REST-API github-pages api swagger-ui api テキストリンク

経緯

「APIの設計書、swaggerで管理しましょう！」「GitHub Pages使えばよくね？」
頭上で飛び交う言葉たちの意味がわからなかったので、調べて使ってみた。

Swagger

Swagger とは、RESTful APIを構築するためのオープンソースのフレームワークのこと。Swagger Spec を書いておけば自動的にドキュメント生成、ドキュメントから実際にリクエストを投げることもできる。

「Swagger Spec」-> Swaggerの書式で記述した仕様書。JSONもしくはYAML形式で記述。

OpenAPI Specification

GitHub Pages

GitHub Pages とは、GitHubがユーザーに提供しているウェブホスティングサービス。基本的に静的なウェブページをホスティングするサービスであるため、データベースを用いるような動的なウェブページは公開できない。また、プライベートリポジトリでも、GitHub Pagesを設定するとインターネット上で公開されるので注意が必要。

導入方法

  • リポジトリを作成し、IntelliJで開く。

  • /docs ディレクトリを作成。

  • Swagger UIリポジトリに含まれる dist ディレクトリをコピーする。
    Swagger-UI

  • 作成した docs ディレクトリ配下に、コピーしてきた dist ディレクトリを配置する。

  • dist/index.html 内のswagger定義の参照先を変更する。

  • ファイル一式をGitHubにPushする。

  • GitHub > Settings > Options > GitHub Pages からGitHub Pagesを有効にする。

  • https://{user_name}.github.io/{repository_name}/ で確認する。

クローン -> ローカルでの動作確認

Swagger-UIから、リポジトリをクローンする。

ちょっと時間がかかるけど、気にせず待機。
swagger-uiリポジトリをクローンできたら、
distディレクトリをコピーしてdocs配下に貼り付ける。

何やらたくさんコピーされた！

ちなみに、ローカル環境で現場どんな見た目なのか見たいときは、
index.hmtl の上で右クリック > Open in Browser > Chrome で見れる。

開発していて今自分どんな見た目のswagger書いてるの？って確認したいとき便利！

今開くと、ペットストアが表示された〜〜

これから自分のswaggerを表示させるため、index.htmlを修正するぞ〜〜！

  • docs 配下に index.html を作成。

  • 作成した index.html に dist 配下の index.html の内容をコピーする。

  • docs 配下の index.html を編集する。

    • 7, 8, 9 行目と、37, 38行目のスクリプトを読み込んでいる箇所のルートを修正。
    • 43行目のurlをspec.yamlに修正。

< docs/index.html > 

<!-- HTML for static distribution bundle build -->
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Swagger UI</title>
    <link href="./dist/swagger-ui.css" rel="stylesheet" type="text/css">
    <link href="./dist/favicon-32x32.png" rel="icon" sizes="32x32" type="./dist/image/png"/>
    <link href="./dist/favicon-16x16.png" rel="icon" sizes="16x16" type="./dist/image/png"/>
    <style>
      html
      {
        box-sizing: border-box;
        overflow: -moz-scrollbars-vertical;
        overflow-y: scroll;
      }

      *,
      *:before,
      *:after
      {
        box-sizing: inherit;
      }

      body
      {
        margin:0;
        background: #fafafa;
      }

    </style>
</head>

<body>
<div id="swagger-ui"></div>

<script src="./dist/swagger-ui-bundle.js"></script>
<script src="./dist/swagger-ui-standalone-preset.js"></script>
<script>
    window.onload = function() {
      // Begin Swagger UI call region
      const ui = SwaggerUIBundle({
        url: "spec.yaml",
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        plugins: [
          SwaggerUIBundle.plugins.DownloadUrl
        ],
        layout: "StandaloneLayout"
      })
      // End Swagger UI call region

      window.ui = ui
    }
  </script>
</body>
</html>

  • docs 配下に spec.yaml を作成。

  • 作成した spec.yaml に設計内容をどんどん書き込む。
    （yamlの書き方はここに書くと長くなるから別記事で！！）

< docs/spec.yaml > 

openapi: 3.0.0
info:
  version: 1.0.0
  title: ポケモン図鑑
paths:
  "/pokemon/{name}":
    get:
      tags:
        - "ポケモン情報取得API"
      summary:
        "ポケモン情報取得API"
      description:
        "指定した名前のポケモンを検索し、情報を取得します。"
      parameters:
        - name: "name"
          in: "path"
          description: "ポケモンの名前"
          required: true
          type: "string"
      responses:
        200:
          description: "Success"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  no:
                    type: "string"
                  name:
                    type: "string"
                  type:
                    type: "string"
                  comment:
                    type: "string"
                example:
                  no: "007"
                  name: "ゼニガメ"
                  type: "みず"
                  comment: "こうらに とじこもり みをまもる。"
        400:
          description: "BadRequest"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  status:
                    type: "string"
                    example: "BAD_REQUEST"
                  message:
                    type: "string"
                    example: "BAD_REQUEST"
        404:
          desctiption: "NotFound"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  status:
                    type: "string"
                    example: "NOT_FOUND"
                  message:
                    type: "string"
                    example: "NOT_FOUND"

準備完了！！！（長かった……。）
docs/index.hmtl の上で右クリック > Open in Browser > Chrome で確認！！

おぉ……

おおおおおおおおおおおおおおおおおおおおおおお！！！！！（嬉しい）

プッシュ -> github上での設定

ローカル環境で動作確認が済んだら、早速プッシュしていくぞい！！

ここであわてんぼう発動…

$ git push origin master
error: src refspec master does not match any

なにこれ…？！と思ったらコミットしてなかった……。
慌てずしっかりコミットしましょう（自戒）

はい！！無事プッシュ完了！！！！
ここからはgithubに移動して設定します〜〜

GutHub > Settings > Options

スクロールしていくと真ん中あたりに GitHub Pages の設定欄が出てくるので、
Sourceに master branch /docs folder を設定！！
この設定をするとdocsリポジトリ以下のものがGitHub Pagesとして公開されるようになる。

設定が完了すると自動でページの一番上まで戻るので、
もう一度真ん中のGitHub Pagesのところにスクロールしていくと、

Your site is ready to be published at xxxxxx

上記の文言が表示がされるので、
xxxxx部分のURLにアクセスして、想定通りに表示されることを確認する。

Fooooooooooooooooooooooooooooo！！！！！！！！！！！！！
やりました！！！！！！！！！！！！！！！！！

まとめ

調べて読んでみて「ふむふむ」と思うだけじゃなくて、実際に手を動かすと理解できていなかったところがわかるからよかった。swaggerの書き方の知識・理解をもっと深めたいと思った。あと、実際に動くとマジで嬉しい。

おまけ