Question - Support of Open API Specification V3

[jmpascal]

Hello,

As Open API Specification V3 has been released this summer, I would know if there's a plan for swagger-maven-plugin to support this new format in the coming period ?

Thanks in advance.

[viktorgunnarson]

I think you posted this question on the wrong project, this is not SpringFox.

SpringFox is here: https://github.com/springfox/springfox

[jmpascal]

My bad I did a false copy/paste ^^'.
The question remains open for the support of OAS 3 within this project.

[ghost]

I'm also curious whether there's any planned support for swagger-core v2. I do realize swagger-core v2 isn't GA yet - just curious.

[charlescapps]

I would also really like support for OAS 3 with swagger-maven-plugin. The tools they provide in swagger-core only let you generate the openApi.json at runtime after the server is running, which is not very helpful for CI/CD and doing things like automatically generating client libs at build/deploy time.

This project is awesome, because you can generate swagger.json in the mvn compile phase, as it should be.

Please add support for OAS 3! Otherwise, we'll need some really backwards hack of starting up a local devserver just to get the openApi.json.

[AnEmortalKid]

I have a working prototype (without unit tests) of something like this here: https://github.com/AnEmortalKid/swagger-maven-plugin/tree/OAS-V3

At the moment, it is it's own goal (since I wanted to work on a separate area), but I think it could be tied to the default generate goal somehow under the apiSource elements.

@who / @kongchen

Would a different goal be preferred or should I try to tie it into the generate goal?

[sniederb]

+1 for OAS 3 support. If that can't be done in the near future, please update your README.md to clearly indicate that while Swagger Spec 2.0 is supported, this plugin still uses the 1.5.x annotations for parsing.

[AnEmortalKid]

@who any thoughts on either including OAS3 support as a separate goal or part of the same goal?

[Gingol]

It would very appreciate to know at least if and when the Open API Specification V3 will be supported.
In the meantime does anyone know an alternative way to create the API documentation during the Maven compile phase?

[AnEmortalKid]

@Gingol you can try with my fork. I added a new goal for this.

[Gingol]

For the moment I added in the pom the exec-maven-plugin in order to run a class during the compile phase.
The main method of this class executes more or less the same operations than getOpenApi method of BaseOpenApiResource class.
@AnEmortalKid When I have some free time maybe I'll try your fork and give you some feedback.

Thanks

[AnEmortalKid]

@who any thoughts on if this should be a new goal or encompassed within generate? Or maybe even a new plugin?

[ender444]

Generate with a version flag to override whatever "default" is landed on (probably 2.0 for now)? I'd personally be fine with either.

[ghost]

Any news on this question? We plan to use your plugin in our CI/CD-Chain (same problem as charlescapps), but since we also use other tools (like pact.io) we would like to use the final OpenAPI Sepcifications.

[marcogrcr]

If you're looking for OpenAPI 3.x support:

1. If you have a javax JAX-RS API: you can use io.swagger.core.v3:swagger-maven-plugin or io.openapitools.swagger:swagger-maven-plugin.
2. If you have a jakarta JAX-RS API: you can use io.swagger.core.v3:swagger-maven-plugin-jakarta.
3. If you have a Spring MVC API:
   • If you can run your server during build, you can use org.springdoc:springdoc-openapi-maven-plugin.
   • Otherwise, you an use the less mature io.github.kbuntrock:openapi-maven-plugin.

References:

• Swagger Version 2.0.X annotations are not supported #655 (comment)
• when support swagger3.0? #881 (comment)
• Updating to jakarta.xml.bind >4 doesn't generate anymore the swaggers #889 (comment)
• Updating to jakarta.xml.bind >4 doesn't generate anymore the swaggers #889 (comment)

[kbuntrock]

If you're looking for OpenAPI 3.x support:

1. **If you have a `javax` JAX-RS API:** you can use [io.swagger.core.v3:swagger-maven-plugin](https://github.com/swagger-api/swagger-core/tree/master/modules/swagger-maven-plugin) or [io.openapitools.swagger:swagger-maven-plugin](https://github.com/openapi-tools/swagger-maven-plugin).

2. **If you have a `jakarta` JAX-RS API:** you can use [io.swagger.core.v3:swagger-maven-plugin-jakarta](https://github.com/swagger-api/swagger-core/tree/master/modules/swagger-maven-plugin).

3. **If you have a Spring MVC API:**
   
   * If you can run your server during build, you can use [org.springdoc:springdoc-openapi-maven-plugin](https://github.com/springdoc/springdoc-openapi-maven-plugin).
   * Otherwise, you an use the less mature [io.github.kbuntrock:openapi-maven-plugin](https://github.com/kbuntrock/openapi-maven-plugin).

References:

* [Swagger Version 2.0.X annotations are not supported #655 (comment)](https://github.com/kongchen/swagger-maven-plugin/issues/655#issuecomment-1349077135)

* [when support swagger3.0? #881 (comment)](https://github.com/kongchen/swagger-maven-plugin/issues/881#issuecomment-1308395438)

* [Updating to jakarta.xml.bind >4 doesn't generate anymore the swaggers #889 (comment)](https://github.com/kongchen/swagger-maven-plugin/issues/889#issuecomment-1652397936)

* [Updating to jakarta.xml.bind >4 doesn't generate anymore the swaggers #889 (comment)](https://github.com/kongchen/swagger-maven-plugin/issues/889#issuecomment-1653285712)

As a side node, the io.github.kbuntrock:openapi-maven-plugin also handle jax-rs and jakarta-rs, not only spring-mvc.