Skip to content

docs: document Maven and Gradle plugin usage in README - #814

Open
Inf1mum wants to merge 1 commit into
OpenAPITools:masterfrom
Inf1mum:docs/339-readme-maven-gradle
Open

Inf1mum wants to merge 1 commit into
OpenAPITools:masterfrom
Inf1mum:docs/339-readme-maven-gradle

Conversation

@Inf1mum

@Inf1mum Inf1mum commented Nov 15, 2026 •

Copy link
Copy Markdown

Fixes #339

The README only described the CLI and the library, so the Maven and Gradle plugins that the project publishes to Maven Central were invisible to anyone landing on the repo page.

This adds:

  • a short note that the project ships as a CLI, a library, and Maven/Gradle plugins (the old wording said it was only a CLI and a library)
  • a "Using the Maven plugin" section: plugin coordinates, the validate goal (bound to the validate phase by default), direct invocation from the command line, and a pointer to the existing options table
  • a "Using the Gradle plugin" section: plugin id and coordinates, the openAPIStyleValidator task, and a buildscript-based setup — the plugin is on Maven Central but not the Gradle Plugin Portal, so the usual plugins {} block alone will not resolve it
  • a link to the sbt plugin maintained outside this project, as requested in the issue

Every snippet was checked against the current plugin sources: the mojo's validate goal and inputFile parameter, and the task name/configuration used by the gradle plugin's own functional test.


Summary by cubic

Documents the Maven and Gradle plugins in the README, which previously only described the CLI and the library. Fixes #339.

  • Adds "Using the Maven plugin" and "Using the Gradle plugin" sections with usage examples verified against the plugin sources.
  • Notes that the Gradle plugin is published to Maven Central but not the Gradle Plugin Portal.
  • Links the sbt plugin maintained outside this project.

Written for commit 7651a85. Summary will update on new commits.

View guided diff

The README only described the CLI and the library, but the project also
publishes a Maven plugin and a Gradle plugin to Maven Central. Add usage
sections for both plugins, verified against the mojo and task sources,
and link the sbt plugin maintained outside this project.

Fixes OpenAPITools#339

Signed-off-by: Inf1mum <vadimlazuk5@gmail.com>

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

3 issues found across 1 file

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. 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. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="README.md">

<violation number="1" location="README.md:202">
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.</violation>

<violation number="2" location="README.md:214">
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`.</violation>

<violation number="3" location="README.md:234">
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.</violation>
</file>

Reply with feedback, questions, or to request a fix.

View guided diff | Re-trigger cubic

Comment thread README.md
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}"

Comment thread README.md

`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.

Comment thread README.md

`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.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Update README.md to talk about the Maven and Gradle plugin and how to use it.

1 participant