MacにSwaggerEditorをインストールしてOpenAPI specを実装する

  • Swaggerとは
  • Swaggerの利用方法
  • SwaggerEditorのインストール
  • OpenAPI specの実装
  • OpenAPI specからGo Serverの実行

Swaggerとは

Swaggerは、API開発フレームワークのオープンソースツールです。OpenAPI仕様のREST API設計・構築・ドキュメント化を行うことができます。

OpenAPIとは、REST APIを記述するためのフォーマットです。OpenAPI specとして、APIの雛形をJsonもしくはYaml形式で記述することができます。OpenAPIの仕様については、こちらに記載されています。

Swaggerには、以下のツールが含まれています。

  • Swagger Editor – ブラウザベースでOpenAPI specを実装することができるツールです。
  • Swagger UI – OpenAPI specからドキュメントをレンダリングするツールです。
  • Swagger Codegen – OpenAPI specからサーバースタブとクライアントライブラリを生成するツールです。

本記事では、Swagger Editorで簡単なOpenAPI specを記述し、Goで実行するところまで紹介します。

Swaggerの利用方法

Swaggerを利用するには、以下の方法があります。

  • オンライン利用・・・リンク先にアクセスしてSwaggerEditorを利用する方法です。
  • ローカル利用・・・SwaggerEditorをダウンロードして利用する方法で、以下の二通りがあります。
    • ローカルファイルによる実行・・・ダウンロードしたSwaggerファイルをブラウザで表示する方法です。
    • Dockerによる実行・・・DockerHubからコンテナイメージをプルして実行する方法です。手順はこちらです。

本記事では、ローカルのSwaggerEditorファイルを利用する方法を紹介します。

SwaggerEditorのインストール

1. GitHubからソースをダウンロードする

$ curl -L -O https://github.com/swagger-api/swagger-editor/archive/v3.11.7.zip

ダウンロードのバージョン情報はこちらです。

2. ファイルを解凍する

$ unzip v3.11.7.zip

3. index.htmlをブラウザで表示する

$ open ./swagger-editor-3.11.7/index.html

以下の画面が表示されます。

OpenAPI specの実装

SwaggerEditorを利用してOpenAPI specを作成します。デフォルトで作成されているyamlファイルはボリュームがあるので、一部を抜き取って編集しました。

swagger: "2.0"
info:
  description: "This is sample api"
  version: "1.0.0"
  title: "Koratta Test API"
  contact:
    email: "koratta@example.com"
host: "localhost:8080"
basePath: "/v2"
tags:
- name: "user"
  description: "User's API"
schemes:
- "http"
paths:
  /user/create:
    post:
      tags:
      - "user"
      summary: "Create user"
      description: "This can only be done by the logged in user."
      operationId: "createUser"
      produces:
      - "application/xml"
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "Created user object"
        required: true
        schema:
          $ref: "#/definitions/User"
      responses:
        default:
          description: "successful operation"
  /user/{username}:
    get:
      tags:
      - "user"
      summary: "Get user by user name"
      description: ""
      operationId: "getUserByName"
      produces:
      - "application/xml"
      - "application/json"
      parameters:
      - name: "username"
        in: "path"
        description: "The name that needs to be fetched. "
        required: true
        type: "string"
      responses:
        "200":
          description: "successful operation"
          schema:
            $ref: "#/definitions/User"
        "400":
          description: "Invalid username supplied"
        "404":
          description: "User not found"
definitions:
  User:
    type: "object"
    properties:
      username:
        type: "string"
      email:
        type: "string"
    xml:
      name: "User"

/user/createにユーザー名とメールアドレスをPOSTし、/user/[ユーザー名]でユーザー情報をGETするAPIです。

yamlを作成すると、画面右側にドキュメントが作成されます。

OpenAPI specからGo Serverの実行

上記で作成したOpenAPI specからGo Serverを実行します。

Swaggerには各言語への変換機能がついており、golangも対応しています。

1.「Generate Server」タブから「go-server」を選択する

2. ダウンロードしたファイルを解凍して実行する

$ go run go-server-server/main.go

そのまま実行すると以下のエラーが出ます。

unexpected directory layout:

main.goのインポートパッケージに相対ディレクトリが使用されているので、＄GOPATHからのディレクトリに変更する必要があります。以下の場合は、$GOPATH/go-server-server/goになります。

main.goの24行目
変更前: sw "./go"
変更後: sw "go-server-server/go"

3. API用curlコマンドを生成する

swaggerはAPIを使用するためのcurlコマンドを生成することができます。

3-1. 使用したいAPIをクリックし、「Try it out」をクリックする

3-2. 使用したいAPIをクリックし、「Try it out」をクリックする

3-3. 生成されたコマンドをコピーする

同じ要領でGETのAPIについても生成しておきます。

4. APIを利用する

手順3で生成したcurlコマンドで、APIを利用します。

$ curl -X POST "http://localhost:8080/v2/user/create" -H "accept: application/xml" -H "Content-Type: application/json" -d "{ \"username\": \"koratta\", \"email\": \"koratta@example.com\"}"
$ curl -X GET "http://localhost:8080/v2/user/koratta" -H "accept: application/xml"
$ curl -X GET "http://localhost:8080/v2/user/koratta2" -H "accept: application/xml"
$

Go Server側でAPIのログが確認できます。

$ go run src/go-server-server/main.go 
2020/07/21 23:43:37 Server started
2020/07/21 23:45:20 POST /v2/user/create CreateUser 3.095µs
2020/07/21 23:48:19 GET /v2/user/koratta GetUserByName 4.464µs
2020/07/21 23:49:55 GET /v2/user/koratta2 GetUserByName 2.33µs

あれ、作成していないkoratta2も同じ結果だ。。と一瞬思いましたが、そもそもAPIの雛形を作成しただけなので、当たり前でした。CreateUserとGetUserByNameのメソッドを確認すると、以下のようにステータス200を返すだけとなっていました。ここからAPIの中身を開発していくようなイメージですかね。

~~go/api_user.goより抜粋~~
func CreateUser(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Content-Type", "application/json; charset=UTF-8")
	w.WriteHeader(http.StatusOK)
}

func GetUserByName(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Content-Type", "application/json; charset=UTF-8")
	w.WriteHeader(http.StatusOK)
}

以上です。なんて便利なツールなんだ。。。

コメント

  1. ピンバック: SwaggerEditorで生成したGo API Serverの処理を実装する – コラッタブログ

コメントは停止中です。