- 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) }
以上です。なんて便利なツールなんだ。。。
コメント
コメントは停止中です。