OASFilter Samples

This interface allows application developers to filter different parts of the OpenAPI model tree. A common scenario is to dynamically augment (update or remove) OpenAPI elements based on the environment that the application is currently in.

The registration of this filter is controlled by setting the key mp.openapi.filter using one of the configuration sources specified in MicroProfile Config. The value is the fully qualified name of the filter implementation, which needs to be visible to the application's classloader.

To use it, simply create an implementation of this interface and register it using the mp.openapi.filter configuration key, where the value is the fully qualified name of the filter class.

Sample META-INF/microprofile-config.properties

mp.openapi.filter=com.mypackage.MyFilter

There are 13 possible filter options:

filterPathItem(PathItem pathItem)
filterOperation(Operation operation)
filterParameter(Parameter parameter)
filterHeader(Header header)
filterRequestBody(RequestBody requestBody)
filterAPIResponse(APIResponse apiResponse)
filterSchema(Schema schema)
filterSecurityScheme(SecurityScheme securityScheme)
filterServer(Server server)
filterTag(Tag tag)
filterLink(Link link)
filterCallback(Callback callback)
filterOpenAPI(OpenAPI openAPI)

All of these methods come with a default implementation that returns the elements as-is.

Here is a sample implementation of the filterOperation method:

    @Override
    public Operation filterOperation(Operation operation) {
        if("operationIdToDelete".equals(operation.getOperationId())){
            return null;  
        } 
    }

In this sample, if this filter is called upon an Operation with the id operationIdToDelete, then it will be deleted, as null is being return.

Here is a sample implementation of filterParameter that updates certain elements:

    @Override
    public Parameter filterParameter(Parameter parameter) {
        if("The user name for login".equals(parameter.getDescription())){
            parameter.setDescription("filterParameter - The user name for login");
        }
        return parameter;
    }

In this sample, any Parameter element with the description "The user name for login" will be updated so that the filterParameter - will be preppended.

There are two rules for calling the filter methods:

1. All filterable descendant elements of a filtered element must be called before its ancestor.
2. The filterOpenAPI method must be the last method called on a filter (which is just a specialization of the first exception).