Repository navigation
docs: document Maven and Gradle plugin usage in README #814
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: master
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -68,7 +68,7 @@ times. I did not validate lately if they still have this feature. | |||||
|
|
||||||
| ## How to use the style validator | ||||||
|
|
||||||
| For now, the project is a simple command line interface (CLI) and a library. The easiest way to use it right now | ||||||
| The project is available as a command line interface (CLI), a library, and Maven and Gradle plugins. The easiest way to use it right now | ||||||
| is to use the CLI and check the output. It will list all errors found based on the options you provided. | ||||||
|
|
||||||
| ### To build | ||||||
|
|
@@ -173,6 +173,70 @@ Example 2: | |||||
| } | ||||||
| ``` | ||||||
|
|
||||||
| ### Using the Maven plugin | ||||||
|
|
||||||
| A Maven plugin is released on Maven Central as `openapi-style-validator-maven-plugin`. Its `validate` goal (bound to the `validate` phase of the build lifecycle by default) fails the build if the specification does not meet the requirements: | ||||||
|
|
||||||
| ```xml | ||||||
| <plugin> | ||||||
| <groupId>org.openapitools.openapistylevalidator</groupId> | ||||||
| <artifactId>openapi-style-validator-maven-plugin</artifactId> | ||||||
| <version>${validatorVersion}</version> | ||||||
| <executions> | ||||||
| <execution> | ||||||
| <goals> | ||||||
| <goal>validate</goal> | ||||||
| </goals> | ||||||
| <configuration> | ||||||
| <inputFile>path/to/spec.yaml</inputFile> | ||||||
| </configuration> | ||||||
| </execution> | ||||||
| </executions> | ||||||
| </plugin> | ||||||
| ``` | ||||||
|
|
||||||
| It can also be invoked directly from the command line (replace `<version>` with the current version): | ||||||
|
|
||||||
| `mvn org.openapitools.openapistylevalidator:openapi-style-validator-maven-plugin:<version>:validate -DinputFile=path/to/spec.yaml` | ||||||
|
|
||||||
| The validation options and naming conventions listed in the Options File table above can be set in the same `<configuration>` element, using the same names (for example `<validateInfoLicense>false</validateInfoLicense>`). | ||||||
|
|
||||||
| ### Using the Gradle plugin | ||||||
|
|
||||||
| A Gradle plugin is released on Maven Central as `openapi-style-validator-gradle-plugin` (the plugin is not published to the Gradle Plugin Portal). It adds an `openAPIStyleValidator` task, in the `Verification` group, that fails the build if the specification does not meet the requirements: | ||||||
|
|
||||||
| ```groovy | ||||||
| buildscript { | ||||||
| repositories { | ||||||
| mavenCentral() | ||||||
| } | ||||||
| dependencies { | ||||||
| classpath 'org.openapitools.openapistylevalidator:openapi-style-validator-gradle-plugin:${validatorVersion}' | ||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. P2: The Prompt for AI agents
Suggested change
|
||||||
| } | ||||||
| } | ||||||
|
|
||||||
| apply plugin: 'org.openapitools.openapistylevalidator' | ||||||
|
|
||||||
| openAPIStyleValidator { | ||||||
| // set the input file option: | ||||||
| inputFile = file('path/to/spec.yaml') | ||||||
|
|
||||||
| // customize the validation options: | ||||||
| validateInfoLicense = false | ||||||
| validateInfoDescription = false | ||||||
| } | ||||||
| ``` | ||||||
|
|
||||||
| The task can then be run with: | ||||||
|
|
||||||
| `gradlew openAPIStyleValidator` | ||||||
|
|
||||||
| The validation options and naming conventions listed in the Options File table above can be set on the task the same way, using the same names. | ||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. P2: Prompt for AI agents
Suggested change
|
||||||
|
|
||||||
| ### Using sbt | ||||||
|
|
||||||
| There is also an sbt plugin, maintained outside this project: [sbt-openapi-style-validator](https://github.com/jrouly/sbt-openapi-style-validator). | ||||||
|
|
||||||
| ## Supported Extensions | ||||||
|
|
||||||
| We sometimes have some paths in our API that are there for legacy reasons. To support this scenario, there is now the possibility to add an extension property in your spec named `x-style-validator-ignored`. Here is an example: | ||||||
|
|
||||||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
P2:
allowedModelPropertiesis listed in the referenced table, but the Maven goal has no parameter for it and never forwards it toValidatorParameters. Users cannot configure that documented exemption through this goal; limit the sentence to exposed options or wire the parameter.Prompt for AI agents