[2.0] Discuss usage of `OASFilter` and `OASModelReader`

Discussion started by @arthurdm in https://github.com/eclipse/microprofile-open-api/issues/251#issuecomment-442157779 :

---

I would like to throw in the idea of removing OASFilter and OASModeReader from the spec in the 2.0 version. The benefits would be an easier-to-understand spec, and would allow full compatibility with an offline (via Maven or other) generation of the OAS3 doc.

I believe that modern usage of OAS3 is either via top-down / design-first, where you have the doc generated by a design team, or bottom-up / code-first, where the developer iteratively works on the JAX-RS app, generating it every time.

In both cases there is a point in time where development is frozen and no more changes to the API should be allowed. Therefore, why would we want to use a dynamic filter or model builder? The only dynamic setting I can reasonably accept are changes to the server element, which can already be achieved by configuring the mp.openapi.servers.* related keys via MP Config.

[charleech]

I apologize for interrupting you.

I’m worried about the wording “remove” and would like to share my OASFilter use case for your consideration.

At the moment I’m using the OASFilter with system properties or environment variable to filter the URL for @SecurityScheme, e.g. the authorizationUrl, tokenUrl, refreshUrl , OpenIdConnectUrl. Because in my environment, dev, sit, uat, prod may use, different host/url, especially a different host where my services are deployed and not in my control. The ability to change those values help me a lot.

The example for my OASFilter is as the following: -

public class DemoOASFilter implements OASFilter {
    @Override
    public SecurityScheme filterSecurityScheme(final SecurityScheme securityScheme) {
        Config config = ConfigProvider.getConfig();
        String myUrl  = config.getValue("my.url", 
                                        String.class);
        securityScheme.getFlows().
                       getImplicit().
                       setAuthorizationUrl(myUrl);

        return securityScheme;
    }
}

The example while deploying is as the following: -

docker run -it \
    --env my.url=http://some/url \
    ....

java -Dmy.url=http://some/url -jar  ....

[lscoughlin]

I have a number of use cases where parts of the api are generate in full or in part based on user configuration of the system at runtime. Removing OASModelReader in particular would pose an enormous inconvenience to me.

Runtime mutability is pretty much exactly what these classes were included for. You’re not required to do anything with them if you don’t understand them but please do not propose removing things just because you personally don’t have a use case.