Motomichi Works Blog

モトミチワークスブログです。その日学習したことについて書いている日記みたいなものです。

OpenAPI (Swagger) に少しだけ入門してmock dataを返すAPIサーバーを起動してみる

制作 open_api

参照したページ

OpenAPI仕様(Swagger仕様)とは

swagger.ioの公式ドキュメント( https://swagger.io/docs/specification/about/ )には以下の記載があります。

OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs.

翻訳すると

OpenAPI仕様(以前のSwagger仕様)は、REST APIのドキュメントを作成するためのファイル記述形式です。

とのことです。

個人的な解釈も混ざっていますが、以下のようなことだと理解しています。

  • Swagger仕様という名称だったものが、今はOpenAPI仕様という名称になった。
  • OpenAPI仕様とはREST APIのドキュメントを作成するためのフォーマット(ファイル記述形式)で拡張子は.jsonか.yaml(.yml)である。
  • OpenAPIファイルのフォーマットに則ってファイルを作成することで、以下の情報を記載したドキュメントを効果的に作成することができる。
    • 使用可能なエンドポイント ( /users) と各エンドポイントでの操作 ( GET /users、POST /users)
    • 操作パラメータ、操作ごとの入出力
    • 認証方法
    • 連絡先情報、ライセンス、使用条件およびその他の情報。

Swaggerとは

swagger.ioの公式ドキュメント( https://swagger.io/docs/specification/about/ )には以下の記載があります。

Swaggerとは、REST API の設計、構築、文書化、および使用に役立つOpenAPI仕様を中心に構築されたオープンソースのツールのセットです。

  • Swagger Editor – OpenAPI 定義を記述できるブラウザーベースのエディター。
  • Swagger UI – OpenAPI 定義をインタラクティブなドキュメントとしてレンダリングします。
  • Swagger Codegen – OpenAPI 定義からサーバー スタブとクライアント ライブラリを生成します。
  • Swagger Editor Next (ベータ版) – OpenAPI および AsyncAPI の定義を記述および確認できるブラウザーベースのエディター。
  • Swagger Core – OpenAPI 定義を作成、使用、操作するための Java 関連ライブラリ。
  • Swagger Parser – OpenAPI 定義を解析するためのスタンドアロン ライブラリ
  • Swagger APIDom – さまざまな記述言語とシリアル化形式にわたって API を記述するための単一の統一構造を提供します。

詳しくは公式ドキュメントを確認してください。

Swagger Codegenからforkして作られたOpenApi Generatorなど新しいツールもあるので、それらも確認しておく必要がありそうです。

アプリケーションを構築

モックAPIを使うアプリケーションを構築します。

Next.js13の開発環境構築手順 step01 yarn create next-app --typescript - Motomichi Works Blog に書いた、

  • create next-app
  • 開発時だけ使用するパッケージをdevDependenciesに移動する

までやりました。

yarn dev すればとりあえずアプリケーションを起動できるようになりました。

OpenAPIファイル(openapi.yaml)を作成する

MockAPIを起動するときにこのファイルが読み込まれます。

mock-data/tmpディレクトリを作成します。

mkdir tmp

ファイルを作成します。

vim tmp/openapi.yaml

openapi.yamlには OpenAPI (Swagger) まとめ - Qiita に倣って以下の通り記述します。

openapi: "3.0.3"

info:
  title: "Sample API"
  version: "1.0.0"

paths:
  "/api/v1/hello":
    get:
      summary: "hello"
      responses:
        "200":
          description: "成功"
          content:
            application/json:
              schema:
                type: string
                example: "hello"

MockAPIを起動するコマンドを定義する

コマンドについては、公式の Installation | Prism を参考にしつつ、少しだけ変えて以下の通りpackage.jsonのscriptsに定義しました。

  "scripts": {
    〜略〜
    "mockapi": "docker run --init --rm -v $(pwd)/tmp:/tmp -p 4010:4010 stoplight/prism:4 mock -h 0.0.0.0 '/tmp/openapi.yaml'"
  },

モックサーバーを起動する

以下のコマンドを実行します。

yarn mockapi

モックサーバーにリクエストしてみる

http://localhost:4010/api/v1/hello にブラウザでアクセスすると、 "hello" と表示されるのが確認できました。

OpenAPIファイル(openapi.yaml)を編集する

OpenAPI (Swagger) まとめ - Qiita を読むと以下のことなどが実践的でわかりやすかったです。

  • openapi.yaml の具体的な書き方
  • VSCodeのextentionの Swagger Viewer で確認する
  • Postman を使用した動作確認

Next.jsのアプリケーションからリクエストしてみる

src/pages/index.tsx を以下の通り編集すると、コンソールにhelloと表示されるのが確認できます。

export default function Home() {
  const data = fetch("http://localhost:4010/api/v1/hello")
    .then((res) => res.json())
    .then((data) => console.log(data));

  return <div>hoge</div>;
}