トップ > プログラミング > go-swaggerを使ってドキュメント生成をしてみる

go-swaggerを使ってドキュメント生成をしてみる

プログラミング

swaggerについてとgo-swaggerを使ったドキュメント生成・ファイル生成までやってみます。

swaggerとは

f:id:utr066:20180310101739p:plain

Swagger is the world’s largest framework of API developer tools for the OpenAPI Specification(OAS), enabling development across the entire API lifecycle, from design and documentation, to test and deployment. https://swagger.io/

go-swaggerインストール

 go get -u github.com/go-swagger/go-swagger/cmd/swagger

swagger記述

yml形式かjson形式で書くことで、ドキュメント生成とコード生成を行ってくれる。

yml形式で書いていきます。

基本的な構成

swagger.ymlは以下のように書いていくみたいです。

swagger: "2.0"
info:
  description: "これはペットストアに関するAPIです。"
  version: "1.0.0"
  title: "Petstore API"
  termsOfService: "http://swagger.io/terms/"
  contact:
    email: "apiteam@swagger.io"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
paths:
  /pet/{petId}:
    get:
      summary: "ペット情報API"
      description: "指定されたpetIdの情報を返します"
      parameters:
      - name: "petId"
        in: "path"
        description: "取得したいペットのID"
        required: true
        type: "integer"
        format: "int64"
      responses:
        200:
          description: "成功時のレスポンス"
          schema:
            type: "object"
            properties:
              id:
                type: "integer"
                format: "int64"
              name:
                type: "string"
                example: "doggie"

http://tech.vasily.jp/entry/swagger_yaml

swaggerファイル作成

swagger init spec

swagger.ymlというファイルができる。

swagger editorを使う

直接swagger.ymlに記述してもいいが、ドキュメントがどのように生成されるかわかりにくい。swagger editorを使うことで、swagger.ymlを書きながら、生成されるドキュメントをみることができる。 * ブラウザで使う・・・swagger editor * ローカルで使う・・・Dockerで起動させる(SwaggerエディターでREST APIの設計書を書いてみる)

ドキュメントを生成する

swagger editor上でswagger.ymlを書き、html形式で出力する。

ドキュメント生成はこれで終わりです。 次は、swagger.ymlを元にコードを生成します。

swagger.ymlを元にファイル生成

swagger.ymlを記述した後、このファイルを元にコードを生成する。

swagger.ymlを記述したらそれを元にコード生成。

//client側のコード生成
$ swagger generate client -f swagger.yml -A swaggertest
//server側のコード生成
$ swagger generate server -f swagger.yml -A swaggertest

上記コマンドを打つと、swagger.ymlに沿ってファイルが生成される。 結構な量のファイルで理解することは難しい。

実装するなら

実装するとなれば、go-swaggerを使うの記事のように、生成されたコードはいじらずに、ファイルを作って処理を書いていくのかなあと思います。

作られているファイルの仕様を理解しないと、データの取り扱いやどこがどうなっているのかわかりません。使うのであれば、swaggerについての勉強は避けられなそうです。

感じたこと

  • ファイルが色々作られ、記述量も多いので、それぞれが何をやっているのかわからない
  • swaggerの理解に苦しめられそう
  • ymlかjsonで記述するが、ドキュメント自動生成は結構楽かもしれない
  • go-swaggerの情報がそこまでない