search

misl / openapi-validator-maven-plugin

Plugin to validate and merge splitted OpenAPI specification files.
6 stars 1 forks source link
json openapi openapi-specification openapi-validation openapi3 swagger yaml

readme

openapi-validator-maven-plugin

A Maven plugin to support validation of and conversion (YAML vs JSON) to OpenAPI (swagger) files using the Swagger Parser library.

It not only verifies whether the API specification files are valid, but also merges splitted files into a single YAML or JSON file. This is especially usefull where tools can not cope with JSON $ref references to external files.

More info on splitted OpenAPI specification files read Design Web APIs

Usage

Add to your build->plugins section (default phase is generate-sources phase)

<plugin>
  <groupId>it.traeck.tools.openapi</groupId>
  <artifactId>openapi-validator-maven-plugin</artifactId>
  <version>1.0.2</version>
  <executions>
    <execution>
      <goals>
        <goal>generate</goal>
      </goals>
      <configuration>
        <inputSpec>${project.basedir}/src/main/resources/api.yaml</inputSpec>
        <outputPath>${project.build.directory}/generated-specification</outputPath>
        <outputFilename>openapi</outputFilename>
        <outputFormat>JSONANDYAML</outputFormat>
      </configuration>
    </execution>
  </executions>
</plugin>

Followed by:

mvn clean compile

General Configuration parameters

Parameter Description Required Default
inputSpec OpenAPI Spec file path true
outputPath target output path false ${project.build.directory}/generated-specification
outputFilename Output filename (without extension) false openapi
outputFormat Output file format (JSON, YAML, JSONANDYAML) false JSON
encoding encoding to use for output files false ${project.build.sourceEncoding}
prettyPrint whether to pretty print (true) output or not false true

Sample configurations

Please see example configurations for how to use this maven plugin.