当サイトは、アフィリエイト広告を利用しています

【OpenAPI】OpenAPIとSwaggerについて調べた

作成日：2024月03月28日
更新日：2024年03月28日

OpenAPIを使ってREST APIの設計をするにあたって
OpenAPIとSwaggerについて調べたことを
忘備録としてまとめておく。

OpenAPIとは何？

OpenAPIとは「OpenAPI Specification」の略でREST APIのコードやドキュメントを生成できるREST API仕様の記述フォーマットのこと。
APIがどのように動作するか、どのようなデータを受け取り、どのようなデータを返すかを定義している。

細かくいうと記述フォーマットなので

  • 何の項目を書く必要があるか？
  • その項目は必須か？
  • その項目はどのようにかけばいいか？

という仕様を定義している

このフォーマットにしたがって作成されたファイル(YAML形式/JSON形式)を

  • OpenAPI仕様に従って作成されたAPI仕様書 = Swagger Spec ファイル（Swagger/OpenAPI Specificationのファイル）

と呼ぶ。

OpenAPI仕様書のことをSwagger Specファイルと書いてることも
多々ある。

記述方法

OpenAPIで書き方の仕様が定義されている（どの項目をどう書けばいいのか）ので
その決まりに従って

  • YAML形式
  • JSON形式

で書くことができる。

OpenAPIの記述フォーマットの具体例

OpenAPIはREST APIの記述フォーマットで
「何の項目をどのような形式で記載すればよいのか」という仕様を定義している
と言われてもイメージつかないと思うので、具体的にみてみる。
※少なくとも自分はよくわからなかった。。。

OpenAPI仕様書を作成

OpenAPIで簡単なAPI仕様書を作ってみる。

OpenAPI仕様書(SwaggerSpecファイル)
openapi: "3.0.0"
info:
  version: "1.0.0"
  title: "Flask API"
paths:
  /:
    get:
      summary: "Hello endpoint"
      responses:
        '200':
          description: "Successful response"
          content:
            text/plain:
              schema:
                type: string
                example: "Hello from Flask!!!"

このYAMLには

  • openapi
  • info
  • paths

というフィールドがある。このうち「openapi」、「paths」は必須。
また上記のフィールドにはサブフィールドがあり、例えば「info」フィールドには

  • title
  • version

がある。このうち、「version」は必須

というような感じで「何の項目」を記載すればいいかが明確に
決まっている。

これが OpenAPIはREST APIの記述フォーマットで
「何の項目をどのような形式で記載すればよいのか」という仕様を定義している

ということだと認識している。

必須でない項目は書かなくてもいい。
詳しくはOpenAPI Specification参照

実際のソース

上記のOpenAPI仕様書の実際ソースは下記になる

apy.py
from flask import Flask


# flaskアプリケーションインスタンス作成
flask_api = Flask(__name__)


@flask_api.route('/')
def hello():
    return "Hello from Flask!!!"

flaskで作ったgetリクエストを受け付けるだけのREST API

Swaggerとは何？

OpenAPIを調べていると必ずセットで「swagger」という文言がでてくる。

そして、～OpenAPIはもともと「Swagger」で～的な文章がでてくるのが
とりあえず無視して

Swaggerは「OpenAPIを用いてREST APIを設計する際に使用するツールセットのこと」と
としておく。

よく使われるものとしては下記がある

Swagger Spec

上記でも書いたがOpenAPI仕様に従って作成されたAPI仕様書のこと

Swagger Editor

Swagger Specの設計書を記載するためのエディタ
Dockerイメージも配布されており、ローカルでの実行も可能。

Swagger UI

OpenAPI仕様書（Swagger Spec）の記述を、動的にAPIドキュメントとしてレンダリングするツール

Swagger Codegen

Swagger Spec で記載された設計からAPIのスタブを自動生成できる

OpenAPIとSwaggerの関係は？

よく意味を混同しやすいOpenAPIとSwaggerについて整理しておく。

  • OpenAPIはREST APIの記述フォーマット
  • SwaggerツールはOpenAPI仕様書（Swagger Spec）を作成するためのツール

OpenAPI仕様書（Swagger Spec）をSwaggerツールを作って作成するので
成果物と手段という感じ。

OpenAPI仕様書（Swagger Spec）の作成方法

VScodeで拡張機能「OpenAPI (Swagger) Editor」を入れれば
VScode上でOpenAPI仕様書（Swagger Spec）を作成できる。

OpenAPI (Swagger) Editorについて

OpenAPI (Swagger) EditorはSwaggerツールでいうと下記の二つが備わっている

  • Swagger Editor
  • Swagger UI

つまり、VScodeでOpenAPI仕様書（Swagger Spec）を作成、編集し
プレビューを確認することができる。
※リアルタイム編集が可能

2024-03-21-23-20-38

また入力補完や入力ミスの警告もしてくれる
右側にでてるのがSwagger UI

よく似た拡張機能として「Swagger Viewer」がある。
こちらもリアルタイム編集ができるので、VScode上でOpenAPI仕様書を
作るなら、どちらかは必須で入れておく必要がある。
※OpenAPI (Swagger) Editorの方が高機能だが、どちらもあまり違いはなさそう。

OpenAPIでできること

VScodeやSwaggerツールを使って作成したOpenAPI仕様書を
利用して下記のことができる。

  • OpenAPIドキュメントの自動生成
  • モックサーバーの構築
  • テストの実行

それぞれ別のツールが必要にはなる。

OpenAPIドキュメントの自動生成

使うツールは「Redoc」
RedocはHTMLベースのドキュメントを生成・閲覧できるようにするツール

OpenAPI仕様書をSwaggerUIよりも見やすいドキュメントとして閲覧、出力できる。

モックサーバーの構築

使うツールは「Prism」
Prismは、API仕様書をもとにモックサーバーを構築するためのツール。

API仕様書から自動でモックサーバーを構築できる

テストの実行

使うツールは「Postman」
Postmanは、APIのテストを実行するためのツール。

API仕様書をimportすることで、テストを作成することができる。

まとめ

OpenAPIを調べると、Swaggerも必ず出てくるので
OpenAPIとSwaggerのそれぞれ何なのか？また二つの関係について
整理してみた。

OpenAPIについてはその他ツール(RedocやPostmanなど)と連携することで、
さらに便利に使えそうなので、おいおい調べて取り入れていきたい。

新着記事

タグ別一覧
top