New Feature: OpenAPI groups and support micronaut @Version

[altro3]

Introducing a new feature: openapi groups (the same feature as in springdoc-openapi). Now you can group endpoints to get multiple swagger files - one file for each group. This is useful when you have multiple API versions or want to separate your API based on some other criteria.

The group settings are very flexible (it was possible to add more settings, but for the first version of the feature it is quite enough). So, a brief introduction to the feature:

1. An OpenAPIGroup annotation can be added to a method, class, or described in package-info.java

@Controller
public class ApiController {

    @OpenAPIGroup("v2")
    @Post("/save/{id}")
    public String save2(String id, Object body) {
        return "OK!";
    }

    @OpenAPIGroup({"v1", "v2"})
    @Post("/save")
    public String save(Object body) {
        return "OK!";
    }
}

With this annotation, you can specify one or more groups that this endpoint will be included in, as well as specify groups from which this endpoint should be excluded.

2. With the help of the new OpenAPIGroupInfo annotation, you can specify the OpenAPIDefinition description that will be inserted into a specific swagger file, only for this group. Thus, you can make different descriptions for different groups.
3. The OpenAPIInclude annotation has been expanded and now you can set groups for endpoints connected from libraries, or remove them from specific groups
4. If you have endpoints tied to a specific group and there are endpoints that are not tied to a group. Toendpoints of unattached groups are considered shared and will be added to all groups
5. API groups are integrated into the swagger UI and if you have multiple groups generated, the swagger UI will add a selector to select the group
   
6. Group settings can be set in any way: through system properties, environment variables, openapi.properties or application.yml file. D The following settings are currently implemented:

micronaut:
  openapi:
    groups:
      v1:
        #The title that will be displayed in the group selector in the UI
        display-name: My API v1
        # A flag indicating that the swagger UI should select this group in the selector by default.
        primary: true
        # The name of the final swagger file. If it is not set, then by default the name will be generated according
        # to the following pattern: swagger-<version>-<groupName>-<apiVersion>. version - application version from the main
        # OpenAPIDefinition annotation, api-version - version from micronaut @Verion annotation
        filename: myapiv1
        # Whether or not to exclude common endpoints from this group
        common-exclude: true
        # An additional way to add or remove endpoints from a given batch group.
        # Strong package matching and inclusion of all subpackages is supported (* symbol)
        packages: com.micronaut.controller.v1.*
        packages-exclude:
          - com.micronaut.controller.v1
          - com.micronaut.controller
      v2:
        display-name: My API v2
      "v3.testv3group":
        packages-exclude:
         - com.micronaut.controller.v3
         - com.micronaut.controller

In addition, the following was done:

1. Added support for annotation Version: processing of this annotation is about the same as for groups. The API description is divided into several files for each version. Query parameters or headers specified in the versioning settings are added to the description of endpoints.

2. Versioning can be combined with groups, so each group will have several different files for each version.

3. css files of swagger UI themes are replaced with minimized copies.

Fixed #952
Fixed #786

[dstepanov]

Does it automatically generate groups for @Version?

[altro3]

Not really. Versions and groups are different entities. You can use only versions or only groups, or you can use groups and versions together.

1. If you use only versions, then a separate swagger file will be created for each version

2. If you use only groups, then each group will have its own swagger file.

3. If you use both groups and versions, then a separate swagger file will be created for each group-version pair

[dstepanov]

I would use one aliasFor depending which value is going to be read

[altro3]

I'm sorry, I don't understand what you're suggesting?

[dstepanov]

The is no point to have two AliasFor, choose one property that you are going to use for reading (names) and only use one alias for value

[altro3]

Sorry, I did not understand what I did wrong and what I should change. I did everything in the same way as this annotation is used in micronaut-core

[dstepanov]

It’s not wrong. Essentially you are going to read only one property like names or value, so it doesn’t make sense to map the value to the other value.

[altro3]

As far as I understand, AliasFor serves to make the annotations more understandable and at the same time leave the ability to write simple annotations without additional property specification. My case is just right for this:

The OpenAPIGroup annotation has 2 fields - names and exclude.

If you specify both values, then we will write like this: @OpenAPIGroup(names = "g1", exclude = "g2").

But often you do not need to specify the groups from which to exclude this endpoint, then the annotation will look like this:
@OpenAPIGroup("g1") . Whihout AliasFor i need to write annotation like this: @OpenAPIGroup(names = "g1")

[dstepanov]

This needs to target next major version

[dstepanov]

Am I correct that you are also modifying the swagger UI? I don't know if that is the best idea. We would have to maintain it instead of copy https://swagger.io/tools/swagger-ui/ files.

Does it produce multiple swagger definitions?

[altro3]

@dstepanov Yes, redoc and rapidoc can't do it out of the box, but swagger-ui supports it out of the box. I didn't change anything in the swagger-ui code.

Why we can't release it with micronaut 3.X ?????

[dstepanov]

Why did you modify openapi/src/main/resources/templates/swagger-ui/theme/monokai.css

I think there are a lot of changes, and v4 will be released soon. WDYT @graemerocher

[altro3]

@dstepanov Not a lot changes. Old functionality works the a as before. This is just new feature.

I described changes css files:

css files of swagger UI themes are replaced with minimized copies.

this is not modified file, just minimized to reduce files size

[dstepanov]

Do you know if we update Swagger UI?

[altro3]

I don't understand. Nobody updates anything, everything is gone as before, I just minimized the theme files for the swagger ui. By the way, it does not belong to swagger ui, this is a separate project of enthusiasts.

[altro3]

My screenshot has a dark theme enabled. If it bothers you, I can take a screenshot with the default theme :-)

[dstepanov]

I know we have a copy of Swagger UI. We might want to update it if there is a newest version

[altro3]

Well, that's what I do. For example here: #1070

It's just that I don't understand why you are talking about updating the swagger UI if these changes do not affect it?

[dstepanov]

Nothing about this PR. I was just wondering if we do update it 😄

[altro3]

I've been updating since I added it here ;-)

[graemerocher]

yeah this should target 4.x only IMO

[altro3]

Personally, I would not want to wait a few more months before the release of the final release 4.0, which most likely cannot be switched to for some time due to bugs (no matter how you test, and after such serious changes there will definitely be bugs).

In addition, micronaut 4 requires java 17, not everyone has switched to java 17 (even I have a couple of services still running on java 8).

These changes do not affect the previous functionality in any way - it works the same as it worked. I can't call it a major change. Just extra functionality.

[dstepanov]

This should definitely target at least a minor release 4.10 but I don't think we plan to release a new minor Micronaut 3.X so it would be better to target v4.

[altro3]

Branch 3.10 has been created for you, I think you will not abandon macronaut version 3, because not everyone will be able to knit and it’s so easy to switch from micronaut 3 to micronaut 4. And few will do it right away. As I said, there will definitely be bugs, and it will also take time due to some changes in the code (for example, change javax to jakarta and maybe something else) and few people are ready to risk correct operation of the system just to switch to a new major version.

In general, I look at this issue as a realist. You have changed the system requirements too much to use micronaut 4. Because of this, it will not be possible to use third-party features that are not directly related to micronaut (like the openapi generator) without switching to the new version of micronaut. It seems to me that your versioning strategy is not entirely correct. It's impossible to develop libraries properly, regardless of micronaut-core.... :-(

In any case, if I were you, I would be ready to release 3.10. Most likely it will be required

[dstepanov]

I guess you can target 4.10, and we will release a new minor version. WDYT @graemerocher

[graemerocher]

build is failing

[altro3]

@graemerocher that was not my fault. Just some problems with gradle repo with your build plugin. I restarted build and now all is ok.

[graemerocher]

Thanks for the contribution!