...

1. Add /api/v1. API version 1, openapi.yaml#version: 1.0.
2. Add backward compatible change to /api/v1.  API version 1, openapi.yaml#version: 1.1
3. Add breacking breaking change to /api/v1, so introduce /api/v2. API version 2, openapi-v2.yaml#version: 2.0, openapi.yaml#version: 1.1.

...

"build time" means that the micronaut annotation processor will discover classes annotated with io.micronaut.http.annotation.Controller and register them as request handlers at server bootstrap. This is done by default but it is always possible to register request handlers at runtime.

Why micronaut

Here is a discussion about adding 3rd party dependencies (micronaut and swagger). The main advantages of micronaut:

• Netty based
• Has a huge community 
• Supports security out-of-the-box

The last point is important. Ignite 3 will definitely need to implement security protocols and strategies. Micronaut already has implementations for the most popular ones, they are tested in production by a community and have a little chance to introduce a vulnerability to the server compering with our own implementation.

Implementation example

@OpenAPIDefinition(
        info = @Info(
                title = "Ignite REST module",
                version = "3.0.0-alpha",
                license = @License(name = "Apache 2.0", url = "https://ignite.apache.org"),
                contact = @Contact(email = "dev@ignite.apache.org")
        )
)
@OpenAPIInclude(classes = {ClusterConfigurationController.class, NodeConfigurationController.class}) // include to openapi specification
public class RestComponent implements IgniteComponent {
    // ...

    public RestComponent(List<MicronautFactory> micronautFactories, RestConfiguration restConfiguration) {
        // register all factories in micronaut context
    }

    @Override
    public void start() {
       // start REST server
    }

...