search

swagger-api / swagger-core

Examples and server integrations for generating the Swagger API Specification, which enables easy access to your REST API
http://swagger.io
Apache License 2.0
7.39k stars 2.18k forks source link

Is there `verify`-like behaviour to fail a CI build if there's a mismatch? #4730

Closed celtric closed 1 month ago

celtric commented 2 months ago

Module: swagger-maven-plugin

I'm looking for something like Sortpom's verify (https://github.com/Ekryd/sortpom/wiki/VerifyFail) but I see that swagger-maven-plugin-jakarta only has a resolve goal. Our goal is for changes in the OpenAPI spec to be reflected in the PR, so the diff can be observed.

Is such functionality available, or in the works?

Thanks

celtric commented 2 months ago

As a workaround we're temporarily using the following in CI:

git status --porcelain | grep -q 'openapi.yaml' && echo "OpenAPI spec is not up-to-date" && git diff && exit 1 || echo "OpenAPI spec is up-to-date"

The feedback happens later, but it allows to keep moving for now.

frantuma commented 1 month ago

@celtric can you clarify which kind of functionality are youi referring to? not sure I understand what would be the goal of verify

celtric commented 1 month ago

@celtric can you clarify which kind of functionality are youi referring to? not sure I understand what would be the goal of verify

We want to make sure that changes to the OpenAPI spec are captured in a PR. Let's say that a developer adds an endpoint in a controller (in code), and forgets to commit the spec automatically generated by swagger-maven-plugin. The PR build will not fail, as swagger-maven-plugin in the PR build will generate a brand new one, and it will be discarded as soon as the runner dies.

Instead, we want to alert the developer when s/he forgets to commit the changes. In that case, we have zero interest in swagger-maven-plugin generating a new spec, and instead what we want it is to tell us (by failing the build) if the committed spec is not aligned with what the annotations say.

This is a similar behaviour as Sortpom, where the sorting is expected to be done by the developer, and the PR build just verifies that it's correct, but doesn't try to fix it.

frantuma commented 1 month ago

@celtric Right, there is no such functionality at the moment unfortunately. PRs as usual are more than welcome..

celtric commented 1 month ago

Thank you for the confirmation @frantuma. I'll close this issue as it's been resolved with a concrete answer. I'll try to carve some time to send a PR in a not-too-long distant future.