Using quarkus-smallrye-openapi how to integrate with REST annotations?

[David Hoffer]

I'm trying to use quarkus-smallrye-openapi to generate a complete Swagger UI page but I can't get it to work.

The basic problem is the generated page all the operations are down at the bottom in a tag called default.

However my operations are annotated with @Operation that has summary, description, responses, tags, etc.  Also the @Parameter descriptions are ignored.  These annotations are from io.swagger.v3.oas.annotations package.

I have tried to add an org.eclipse.microprofile.openapi.annotations.OpenAPIDefinition annotation to a class that extends javax.ws.rs.core.Application but that just adds info to the top of the page...the content is not integrated using those tags, etc.

How can I create a complete/integrated Swagger UI page using quarkus-smallrye-openapi ?

I'm using 1.13.7.Final

-Dave

[Phillip Kruger]

Hi, we do not support swagger annotations. Replace the swagger annotations with the microprofile annotations and add a @tag annotation. 

--
You received this message because you are subscribed to the Google Groups "Quarkus Development mailing list" group.
To unsubscribe from this group and stop receiving emails from it, send an email to quarkus-dev...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/e58494c7-3b02-4887-ae63-8f2f09f17b8fn%40googlegroups.com.

[David Hoffer]

Are the microprofile annotations documented somewhere?  I did not find them.

Dave

[Bruno Leonardo Gonçalves]

The MicroProfile OpenAPI annotations [1] supported by quarkus-smallrye-openapi extension are defined on "org.eclipse.microprofile.openapi.annotations" package.

Maybe that definition could be explicitly pointed at Quakus OpenAPI guide about the annotations [2].

[1] https://download.eclipse.org/microprofile/microprofile-open-api-2.0/microprofile-openapi-spec-2.0.html#_annotations

[2] https://quarkus.io/guides/openapi-swaggerui#providing-application-level-openapi-annotations

To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/CAA8BW8ETYB7AMWKaP%2BT%3DQMfuHtft6WKUpsQ-hkTt6HQz%2BBOuMw%40mail.gmail.com.

[David Hoffer]

Yes, that would be a great idea.  And update the samples in the Quarkus  OpenAPI site to show these in usage.  Currently it just shows the 'default' page which is not acceptable in use, so then one gets the impression that is all that is supported at this point.  I will look for the annotations as you suggested.

-Dave

[David Hoffer]

Also can you elaborate on what dependencies one needs in Quarkus for this?

Per the Quarkus docs I have added the following:

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-smallrye-openapi</artifactId>
</dependency>

But it's not clear to me that brings in the code you just referenced.

-Dave

[Bruno Leonardo Gonçalves]

The Quarkus smallrye-openapi has the MicroProfile OpenAPI as transitive dependency.

- io.quarkus:quarkus-smallrye-openapi
   - io.smallrye:smallrye-open-api-core
      - org.eclipse.microprofile.openapi:microprofile-openapi-api

The "microprofile-openapi-api" artifact contains the annotations supported to define service capabilities for an OpenAPI interface description.

[David Hoffer]

Thanks yeah I see that now, my code editor just was slow to find those.  The only one I don't see yet is how to handle arrays of objects in responses, Swagger has @ArraySchema how is this handled using microprofile?

-Dave

[David Hoffer]

Found it...type = SchemaType.ARRAY

One last question hopefully.  How do I add role based security for the Swagger UI endpoint?  E.g we are starting to use @RolesAllowed for all our endpoints, we need to do the same for the Swagger UI, how?

-Dave

[George Gastaldi]

Maybe https://github.com/quarkusio/registry.quarkus.io/blob/main/src/main/java/io/quarkus/registry/app/admin/AdminApi.java might help

To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/CAA8BW8GS27OWZk%2BWU1u0WD_fZ74i%2BufBZmt3htw0YqK7a%2Bnr8A%40mail.gmail.com.

[Phillip Kruger]

Yes, roles allowed plus some more (for now) see https://github.com/phillip-kruger/openapi-security-example

In the future, roles allowed will be the only requirement for most cases as we will automatically add security based on the extension.

Also see 

https://youtu.be/8JsnjHQM36k

From around 40mins onwards

Cheers