OpenAPIとSwaggerでhello worldを表示

OpenAPIとSwaggerでhello worldを表示するサンプルです。Node.jsでも確認します。
(確認環境:Windows 10,Google Chrome,open api 3.0.3,Node.js v12.14.0)

目次

サンプル OpenAPIとは
Swagger Editorでhello worldを表示
  node.jsを使用してhello worldを表示

OpenAPIとは

RESTful APIの標準的なフォーマットの仕様です。
JSONとYAMLがあります。

OpenAPI Initiative (OAI)が管理していてマイクロソフトやGoogle等も関わっています。

https://www.openapis.org/

Swaggerはツールで、APIドキュメントの生成やHTTPリクエストの作成やテストも行なえます。

 

Swagger Editorでhello worldを表示

最初にSwagger EditorでOpenAPIのhello worldを表示させます。

1.Swagger Editorのページを表示します。
https://editor.swagger.io/

 

2.以下は、hello worldのコードです。Swagger Editorの左側にはりつけます。

openapi: "3.0.3"

info:
  title: "Test1-API"
  version: "1.0.0"

paths:
  "/helloWorld":
    get:
      responses:
        "200":
          description: "test-ok"
          content:
            application/json:
              schema:
                type: string
                example: "Hello World"

1行目のopenapiは、必須項目です。openapiのバージョンを指定します。
3~5行目のinfoのtitleとversionも必須項目です。このapiの情報です。
7行目のpathsも必須項目です。
openapiとinfoとpathsはルートオブジェクトと呼ばれます。
ルートオブジェクトはこの他にserversとtagsとsecurityとcomponentsがあります。
データはYAML形式です。インデントで階層構造を表します。JSON形式でも可です。

 

3.左側にコードを貼り付けると右側にリアルタイムで仕様が表示されます。
右側の部分は、Swagger UIです。
コードのエラーがあった場合、右側にエラー情報が表示されます。

 

4.GETの欄をクリックするとAPIの仕様が下に展開されます。
try it outボタンを押すとテストを行えるようになります。

仕様としては、GETで/helloWorldにパラメータなしでアクセスし、正常(200)のときは、文字列が返ります。

 

5.Executeを押すと実行します。

 

6.実行結果です。
Curlの欄は、コピーしてコマンドプロンプトからも実行できます。
URLの欄は使用されたURLが表示されます。
ResponsesにHello Worldが表示されました。

 

node.jsを使用してhello worldを表示

前提:node.jsのインストールとパスの設定が完了している必要があります。

1.Swagger Editorの上部にあるGenerate Serverからnodejs-serverをクリックします。
nodejs-server-server-generated.zipというzipファイルがダウンロードされます。

 

2.zipファイルを任意の場所で展開します。

 

3.コマンドプロンプトでzipファイルを展開した場所に行き以下のコマンドを入力します。

npm start

赤線の部分にSwagger UIを使用できるURLが表示されます。

 

4.上記のhttp://localhost:8080/docsにアクセスするとローカルにSwagger UIが表示されます。

Webページの時と同じように、Executeボタンを押すと実行され、Hello Worldが表示されます。

 

以下は、OpenAPIの仕様書のリンクです。
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md

関連の記事

OpenAPIの設定(servers/tags/security/components)
JSONのデータ型とは+JSON整形ツール

△上に戻る