Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 65 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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>`).

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: allowedModelProperties is listed in the referenced table, but the Maven goal has no parameter for it and never forwards it to ValidatorParameters. Users cannot configure that documented exemption through this goal; limit the sentence to exposed options or wire the parameter.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At README.md, line 202:

<comment>`allowedModelProperties` is listed in the referenced table, but the Maven goal has no parameter for it and never forwards it to `ValidatorParameters`. Users cannot configure that documented exemption through this goal; limit the sentence to exposed options or wire the parameter.</comment>

<file context>
@@ -173,6 +173,70 @@ Example 2:
+
+`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
</file context>
Suggested change
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>`).
The boolean 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>`). The `allowedModelProperties` option is not currently exposed by this plugin.


### 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}'

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: The classpath value is single-quoted, so ${validatorVersion} is passed literally and the documented build cannot resolve the plugin. Use a double-quoted string and define or replace validatorVersion.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At README.md, line 214:

<comment>The `classpath` value is single-quoted, so `${validatorVersion}` is passed literally and the documented build cannot resolve the plugin. Use a double-quoted string and define or replace `validatorVersion`.</comment>

<file context>
@@ -173,6 +173,70 @@ Example 2:
+    mavenCentral()
+  }
+  dependencies {
+    classpath 'org.openapitools.openapistylevalidator:openapi-style-validator-gradle-plugin:${validatorVersion}'
+  }
+}
</file context>
Suggested change
classpath 'org.openapitools.openapistylevalidator:openapi-style-validator-gradle-plugin:${validatorVersion}'
classpath "org.openapitools.openapistylevalidator:openapi-style-validator-gradle-plugin:${validatorVersion}"

}
}

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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: allowedModelProperties is listed in the referenced table, but the Gradle task has no property or setter for it and never forwards it to validation. Limit this claim to options exposed by the task or add the missing task wiring.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At README.md, line 234:

<comment>`allowedModelProperties` is listed in the referenced table, but the Gradle task has no property or setter for it and never forwards it to validation. Limit this claim to options exposed by the task or add the missing task wiring.</comment>

<file context>
@@ -173,6 +173,70 @@ Example 2:
+
+`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.
+
+### Using sbt
</file context>
Suggested change
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.
The boolean 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. The `allowedModelProperties` option is not currently exposed by this task.


### 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:
Expand Down