Quick start

This is documentation for version 0.2.0.

<plugin>
  <groupId>net.mwalser</groupId>
  <artifactId>openapi-toolkit-maven-plugin</artifactId>
  <version>0.2.0</version>
  <executions>
    <execution>
      <id>lint</id>
      <goals>
        <goal>lint</goal>                 <!-- runs in the validate phase -->
      </goals>
    </execution>
    <execution>
      <id>bundle</id>
      <goals>
        <goal>bundle</goal>               <!-- runs in the generate-resources phase -->
      </goals>
      <configuration>
        <addResource>true</addResource>   <!-- package the bundle in the JAR -->
      </configuration>
    </execution>
  </executions>
</plugin>

Put the API description under src/main/openapi/ and add a redocly.yaml next to the POM:

extends:
  - recommended
apis:
  petstore:
    root: src/main/openapi/openapi.yaml
rules:
  security-defined: warn   # downgrade a rule; `off` disables it

mvn package lints src/main/openapi/openapi.yaml, writes the bundle to target/generated-resources/openapi/petstore.yaml and packages it as petstore.yaml in the JAR. An execution of build-docs also renders an HTML reference page, target/generated-resources/redoc/petstore.html.

Problems with severity error fail the build (Lint failed with 2 errors.); warnings do not. Change severities under rules: or pick a smaller ruleset such as minimal (see Redocly's rules).

Once the plugin is declared in the POM, every goal also runs from the command line. Without a redocly.yaml, pass the files and the built-in recommended ruleset applies:

mvn openapi-toolkit:lint -Dopenapi.toolkit.apis=src/main/openapi/openapi.yaml

Goals

Next: usage and examples for each scenario, the goal reference for every parameter, limitations, and performance for the optional native engine.