Generating schema for classes without annotation

[anarsultanov]

Hello,

I'd like to know if it's possible to create an OpenAPI schema from JAX-RS classes that do not have the @Path annotation using the smallrye-open-api-maven-plugin.

My use case is that I implement Keycloak extensions with custom REST endpoints, for which I would like to generate documentation using the above plugin, but ran into a problem. The problem is that the plugin doesn't recognize my resource without the @Path annotation, but if I add the annotation, the extension won't work properly because Quarkus will try to initialize it as a bean, which results in failure due to unsatisfied dependencies.

I would greatly appreciate any advice or suggestions on how to overcome this issue.

[phillip-kruger]

@MikeEdgar ? Any thoughts ? @anarsultanov is it possible to see something ? like an app or reproducer ?

[anarsultanov]

would be placed in the OpenAPI document under an incorrect path

This is not a problem for me, I solve it by setting an empty path in annotation and specifying correct path in the "servers". But I afraid that quarkus will also expose the endpoints on the path specified in annotation.

This may be an option, maybe something like @SmallRyeOpenAPIPath(value = "/your/path")

Something like this will definitely solve my issue.
I'd be happy to contribute to its implementation, however, I would appreciate guidance on where to begin, as I am not familiar with the codebase.

[MikeEdgar]

@anarsultanov , I think the simplest would be to add that annotation in the core project in io.smallrye.openapi.api.annotations (a new package). You would then add its name to the JAX-RS array used to find path elements [1] and add an associated test (or tests) to the JAX-RS extension module.

[1]

smallrye-open-api/extension-jaxrs/src/main/java/io/smallrye/openapi/jaxrs/JaxRsConstants.java

Lines 25 to 27 in a64b6af

	static final Set<DotName> PATH = new TreeSet<>(Arrays.asList(
	DotName.createSimple("javax.ws.rs.Path"),
	DotName.createSimple("jakarta.ws.rs.Path")));

[anarsultanov]

Thanks @MikeEdgar, I've created a small PR introducing this annotation: #1365
I wasn't sure how many test cases I needed to cover, given that it can only be applied at the class level, so I added just one simple test.

[codespearhead]

That PR [1] was closed in favor of [2], which was merged on 2023-03-01T00:33:19Z.

@anarsultanov Can you mark this comment as the answer so it doesn't show up as unanswered in the GitHub discussions tab?

[1] #1365
[2] #1369

[tsaarni]

I was looking to document a Keycloak REST API extension and ended up here. I couldn’t find this feature documented anywhere, but I discovered how to use it thanks to this snippet in @anarsultanov 's project

            <plugin>
                <groupId>io.smallrye</groupId>
                <artifactId>smallrye-open-api-maven-plugin</artifactId>
                <executions>
                    <execution>
                        <phase>compile</phase>
                        <goals>
                            <goal>generate-schema</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <outputDirectory>${project.basedir}/docs</outputDirectory>
                    <infoTitle>${project.name}</infoTitle>
                    <infoVersion>${project.version}</infoVersion>
                    <servers>{{keycloakUrl}}/auth/realms/{{realmName}}</servers>
                    <scanResourceClasses>
                        <dev.sultanov.keycloak.multitenancy.resource.TenantsResource>/tenants</dev.sultanov.keycloak.multitenancy.resource.TenantsResource>
                    </scanResourceClasses>
                </configuration>
            </plugin>

The resource class dev.sultanov.keycloak.multitenancy.resource.TenantsResource doesn't use the @Path annotation, but its base path is overwritten as /tenants.

Thank you for this feature @anarsultanov!