https://int128.hatenablog.com/entry/2016/12/04/004553

Swagger YAMLを書いていると間違いに気づかないことがよくあります。リポジトリにpushした時にJenkinsやCircle CIなどで構文チェックできるとミスを防げるます。そこで、GradleのプラグインにSwagger YAMLのバリデーションを追加してみました。

使い方

build.gradleに下記を書きます。

plugins {
  id 'org.hidetake.swagger.generator' version '1.6.0'
}

validateSwagger {
  inputFile = file('petstore.yaml')
}

下記のようにvalidateSwaggerタスクを実行すると、YAMLのバリデーションが実行されます。

% ./gradlew validateSwagger
:validateSwagger

YAMLに間違いがあると、下記のようなエラーを表示してくれます。

:validateSwagger FAILED

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':validateSwagger'.
> Invalid Swagger YAML: /Users/hidetake/repo/gradle-swagger-generator-plugin/acceptance-test/validator/petstore.yaml
  ---
  - level: "error"
    schema:
      loadingURI: "http://swagger.io/v2/schema.json#"
      pointer: "/definitions/parametersList/items"
    instance:
      pointer: "/paths/~1pets~1{petId}/get/parameters/0"
    domain: "validation"
    keyword: "oneOf"
    message: "instance failed to match exactly one schema (matched 0 out of 2)"
    matched: 0
    nrSchemas: 2
(以下略)

仕組み

Swaggerで公式に用意されているJSON スキーマでYAMLを検証しています。

https://github.com/OAI/OpenAPI-Specification/blob/master/schemas/v2.0/schema.json

Gradleプラグインについて

Gradle Swagger Generator Pluginはバリデーションだけでなくコード生成やドキュメント生成の機能も提供しています。詳しい使い方はREADMEを参照してください。

github.com