open api
投稿日
投稿者 dennie

【OPEN API】OPEN APIとは何か

OPEN API は WEB API の開発を手助けしてくれるツールまたはフレームワークです。

WEB API の開発を行う手順として以下が行えます。

  • 仕様定義 – API 仕様の作成
  • 仕様定義公開 – API利用者へ API 仕様の提供
  • モックアップ作成 – API利用者へ API の試し利用

今までの開発の問題点

今までの開発では以下のような問題点がありました。

問題点
  1. WEB API 定義書の記載は、統一された基準やフォーマットがなく決まっていないので見方が難しい。
  2. WEB API 開発者はAPI呼び出し側の開発前にモックアップを作成する必要があった。
  3. APIの仕様はドキュメント(PDFやエクセル)などに記載し、呼び出し元へドキュメントを提出する必要があった。
  4. APIの仕様をWEBに公開する際に、APIの仕様を記述したWEBページを作成する必要があった。

OPEN APIでできること

主に以下の2点が行えます。

できること
  1. WEB API の定義
  2. WEB API のモックアップ作成

OPEN APIのメリット

主に、以下がメリットになり、利便性が高いことが分かります。

バージョン管理

YAML、JSONファイルで定義する為、バージョン管理や共有が容易になります。

共通フォーマットによる共有

OPEN API の仕様に従い記述するので、APIの読み書きが統一され共有しやすくなリます。

WEB API のモックアップ

WEB API の仕様を記述したYAMLまたはJSONファイルからWEB API のモックアップを作成することができるので、開発中に簡単にWEB APIのモックアップを公開できます。
または、WEB API の仕様を記述したYAMLまたはJSONファイルを呼び出し側へ提供し、呼び出し側でモックアップを作成し利用してもらうことも可能です。

WEB APIの仕様公開

WEB API の仕様を記述したYAMLまたはJSONファイルからWEB API の仕様をHTMLファイルで出力できるので、WEB API の利用者はブラウザから WEB API の仕様を確認できます。

OPEN APIの記述

OPEN API の形式に従い、YAMLまたはJOSNファイルに記述します。
YAMLやJSONを自分のPC内のエディターで編集することも可能ですが、swagger editor(webサイト) からオンラインで記述した内容を確認することもできます。

Swagger editor

https://editor.swagger.io/

記述の誤りも検知してくれるので、Swagger editorを使うと良いでしょう。

モックアップ作成

簡単にモックアップを作成することができます。

最後に

今回はOPEN APIは何ができるのかをメリットと共に説明しました。
次回は、OPEN API を 定義して簡単なWEB APIを定義します。

© DeNnie.Lab All Rights Reserved.