How can I properly display "overloaded" URL when using content negotiation

[maecval]

Hi all,

We are using content negotiation (based on accept-header) for versioning the REST resources in our SpringBoot applications.
How can this be properly displayed in Swagger-UI?

We'd like to have

• either 2 separate operations be listed in the Swagger-UI (one per version)
• or 2 groups containing one version each (grouping done by either an own annotation or by evaluating the io.swagger.v3.oas.annotations)

(?) Can we e.g. use GroupedOpenApi (for example in combination with OperationCustomizer) to define 2 groups (let's say "Current" and "Deprecated") to seperate the versions?

I could not figure out how to create these groups.

The annotation io.swagger.v3.oas.annotations.Operation supports the "hidden" attribute. But this is not reflected in io.swagger.v3.oas.models.Operation. Hence the "operation" can not be modified to be hidden if it does not match the corresponding group.

(?) Can the Operation be "filtered out" in a, OperationCustomizer ?

Or how could we solve this issue?

NOTE:
This came up when migrating to Spring Boot 2.3 and updating to springdoc-openapi-ui.
Previsouly we used an approach with api selectors in the Docket in one of our apps:

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    ...
    ...
    @Bean
    public Docket swaggerSpringMvcPluginDeprecated(
        @Value("${info.app.name}") String name,
        @Value("${info.app.description}") String description,
        @Value("${info.app.version}") String version,
        @Value("${info.app.team}") String team,
        @Value("${info.app.url}") String url,
        @Value("${info.app.contact}") String contact
    ) {
        return new Docket(DocumentationType.SWAGGER_2)
            .useDefaultResponseMessages(false)
            .select()
            .apis(selector -> Objects.requireNonNull(selector).isAnnotatedWith(DeprecatedAPI.class))
            .build()
            .apiInfo(new ApiInfo(name, description, version, null, new Contact(team, url, contact), null, null, Collections.emptyList()))
            .groupName("Deprecated");
    }

I highly appreciate any help :-).
Kind regards,
Valentin

[bnasslahsen]

@maecval,

You can have a look at a sample code for creating groups depending on header values: #449

[maecval]

@bnasslahsen
Thanks for the quick response.
But I do not think that the referenced issue contains a solution to this problem.
I could not yet manage to get it working; i.e. could not create groups depending on the operation's "deprecated" flag.
If I check for that, the whole path gets removed even tough there is a non-deprecated version for the same path.

A filtering based on the io.swagger.v3.oas.annotations.Operation would be required before the OpenApi gets built.
It used to worked liked described with the previous Docket-based solution. This seems to be lost !

[bnasslahsen]

@maecval,

With OpenApiCustomiser, you can have access the OpenAPI Object, and do whatever filtering you want.
Note that you can not only fitler paths, but you also replace or remove any Operation you want.

If you have diffculties to write code to filter depending on deprecated attribute, you can add the sample springdoc-openapi code you have started and we can help you on that.

Also, there no need to write your comment on many issues.

[maecval]

Hello, Thanks for your support. I was debugging the whole stuff and the problem is clear now: The OpenApi object does not have the required information because it contains merged data. There are 2 GET operations in the source code for the same URL; lets say ".../pets". They differ in the "produces" attribute of the RequestMapping which makes Spring dispatching to the correct method based on the "accept" header. - one defines the produces attribute as "...v1" - one defines the produces attribute as "...v2" These methods are documented with the opanapi / swagger v3 annotations (io.swagger.v3.oas.annotations). The problem is that the process creating the OpenAPI (model) object merges the documentation of these 2 methods ! (in class: OperationBuilder, method: parse) It results in 1 operation (model) object representing this. That means that information got lost. There is no way to filter/search for this information in the OpenAPI object because it simply is *NOT* present there. If we have to replace the operation (model) object we need to have the "handleMethod" which provides the correct information; i.e. one needs to analyse the handleMethod's annotation and create the correct information. That would mean to recreate the information which was lost when the data got "merge" during the creation of the OpenAPI model object. There should be more help by the library... Maybe we are going to build a tiny app to show you the issue. But currently it looks as if we have to roll back our changed applications to the swagger v2 :-(. Regards, Valentin

…

On Fri, 25 Sep 2020 at 11:54, bnasslahsen ***@***.***> wrote: @maecval <https://github.com/maecval>, With OpenApiCustomiser, you can have access the OpenAPI Object, and do whatever filtering you want. Note that you can not only fitler paths, but you also replace or remove any Operation you want. If you have diffculties to write code to filter depending on deprecated attribute, you can add the sample springdoc-openapi code you have started and we can help you on that. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#878 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ADJQT2PMTWMU6LNOFAAHYJDSHRSELANCNFSM4RX574OQ> .

-- ===================== Valentin Maechler Rosengartenstrasse 5 8853 Lachen

[bnasslahsen]

@maecval,

We will wait for your minimal reproducible sample and will be happy to help.

[maecval]

@bnasslahsen here's some sample code which I hope demonstrates the issue.
Find the 2 zip file in the attachments.

---

Sample application to demonstrate the issue when trying to document accept-header-versioning with springdoc

[Valentin Maechler aka maecval, 2020-09-25]

sample-app-1.zip

The sample application contains 1 REST resource class with

• 2 getter methods which map to Http-GET on /{id}: getSampleV1 and getSampleV2 which differ only in the produces value (accept header)
• 1 search method which maps to Http-POST on /search

When running the code contained in sample-app-1.zip the OpenAPI definition on
http://localhost:8080/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config#/
shows 1 GET method at /{id} which is marked as Warning: Deprecated BUT has the description of the non-deprecated V2: "Get the sample by its id. This represents V2."
The drop down for the Media type in the Responses sections contains both types: V1 and V2
This is caused by the "merged" OpenAPI data!
The version 2 is not defined as deprecated...

This is incorrect!

sample-app-2.zip

This code enhances the sample-1 by adding 2 GroupedOpenApi in the OpenApiConfig class.

desired result

We would like to have 2 groups in the "Select a definition" dropdown box: "v1 group" and "v2 group"

• "v1 group": shall contain the details about the getSampleV1 method
• "v2 group": shall contain the details about the getSampleV2 and the `` methods

By details we mean, e.g. the correct description, ...

status of sample code

I was able to get the following definitions shown:

• "v1 group": containing just 1 entry for a Http-GET on /{id}; it's grey which looks like disabled (is ok for getSampleV1)
  BUT its description did not represent the getSampleV1 method:
  • the description is "Get the sample by its id. This represents V2."
  • the responses dropdown contains 2 entries: V1 and V2 where I'd expect only V1
• "v2 group": containing 2 entries:
  • 1 for a Http-GET on /{id}
    • it's grey which I do not expect for getSampleV2
    • the input parameter is a string which does not match getSampleV2; it should be an integer
    • the responses dropdown contains 2 entries: V1 and V2 where I'd expect only V2
  • 1 for a Http-POST which seems to be correct

Can you please modify the sample to produce the desired output/display?

Thanks for your help !

sample-app-1.zip
sample-app-2.zip

[bnasslahsen]

@maecval,

For the sample-app-1.zip, what you are expecting is incorrect.

OpenAPI defines a unique operation as a combination of a path and an HTTP method. This means that two GET or two POST methods for the same path are not allowed

In other words, it doesn't make sense to have for the same path/HTTP method two swagger @Operation annotations: You can only have one operation in the resulting OpenAPI description.

More details can be available here:

• https://swagger.io/docs/specification/paths-and-operations/

This is said, for sample-app-2.zip it's different: From OpenAPI spec perspective, it should be possible to get two different OpenAPI description, each one referencing the same path/HTTP method, even with different attributes.

A convenient option will be added in the next release to support the filtering in GroupedOpenApi level.
You will be able to filter by produces mediaType as follows:

@Bean
public GroupedOpenApi groupV1OpenApi() {
	return GroupedOpenApi.builder()
			.group("v1-group")
                        .producesToMatch(Application.VERSION_1)
			.build();
}

Meanwhile, the support is now available with the latest snapshot.

[maecval]

Dear @bnasslahsen ,

Thanks for these explanations.

I try to give some more information about the "filtering" using the groups.
In sample-2 there were 2 groups added to filter by version (v1 and v2).
The grouping/filtering is done on the OpenAPI object (method customise(OpenAPI openApi)).
But the result is incorrect either (like asmple-1 which you explained). I hope you agree with this.
The reason is that the OpenAPI object passed in customise(OpenAPI openApi) already misses the corresponding details (v1, v2).
If the filtering/grouping would be done at an earlier stage; i.e. before building the openApi object, it would contain consistent information later on.
This was the case with springfox's Docket approach.

As far as I understand there is no way to get the desired groups for v1 and v2 (in regards to the sample-2 app) correctly grouped/filtered, right?

I attached the actual and (manually created) desired JSON outputs for the REST resources defined in the sample apps.

Kind regards.

P. S. sample usage of springfox's Docket (i.e. selector):

    @Bean
    public Docket currentDocket
[sample-json-files.zip](https://github.com/springdoc/springdoc-openapi/files/5290138/sample-json-files.zip)
(
        @Value("${info.app.name}") String name,
        @Value("${info.app.description}") String description,
        @Value("${info.app.version}") String version,
        @Value("${info.app.team}") String team,
        @Value("${info.app.url}") String url,
        @Value("${info.app.contact}") String contact
    ) {
        return new Docket(DocumentationType.SWAGGER_2)
            .useDefaultResponseMessages(false)
            .select()
            .apis(selector -> Objects.requireNonNull(selector).isAnnotatedWith(CurrentAPI.class))
            .build()
            .apiInfo(new ApiInfo(name, description, version, null, new Contact(team, url, contact), null, null, Collections.emptyList()))
            .groupName("Current");
    }

[bnasslahsen]

@maecval,

As far as I understand there is no way to get the desired groups for v1 and v2 (in regards to the sample-2 app) correctly grouped/filtered, right?

No. You can get the the desired groups for v1 and v2 as explained on my comment above, using v1.4.8, and the producesToMatch option of GroupedOpenApi.

Your example, is illustrated in tests here:

• springdoc-openapi/springdoc-openapi-webmvc-core/src/test/java/test/org/springdoc/api/app134/OpenApiConfig.java

  Line 14 in 0346b6a

  .group("v1-group").producesToMatch(HelloController.VERSION_1)

[maecval]

@bnasslahsen,

Thanks I will give it a try.
(and come back to you if we still struggle :-))

Cheers !

[maecval]

@bnasslahsen,

Thanks !
Works perfectly with the latest version 1.4.8 !

Cheers !

[Govindmallurwar]

@bnasslahsen,

Thanks !
Works perfectly with the latest version 1.4.8 !

Cheers !

can you please provide me updated zip file of the code after it works for you?