Package de.aristaflow.ilm.ws.rest.base.service.openapi

Class Enricher

java.lang.Object
de.aristaflow.ilm.ws.rest.base.service.openapi.Enricher
All Implemented Interfaces:
io.swagger.v3.core.converter.ModelConverter
public class Enricher extends Object implements io.swagger.v3.core.converter.ModelConverter
This class handles enriching operations, parameters and types of the OpenAPI. It adds constraints stemming from validation annotations (from javax.validation.constraints) as well as Default. This includes more annotations than already considered by Swagger (ParameterProcessor).
Besides it enriches operations by adding responses declared via the rather simple annotation OperationResponse. This also includes some sophisticated handling of the default response: Its schema may be referred to by OperationResponse. The response considered as default by the OpenAPI generator will become the response for status code HttpURLConnection.HTTP_OK (or HttpURLConnection.HTTP_NO_CONTENT) if there is no explicit response declared for this status code.
An exceptional response for server errors will be added for code "5XX" containing an IlmException.

This Enricher also adapts type resolution for byte[] used in operations and String[].class used in schema declarations. The first prevent Swagger from creating an array of strings representing bytes; the string is already a container type, so the surrounding array is nonsense.
The second adaption allows to use array classes within the properties of Schema expecting Class. Without that adaption, such classes would be ignored. This enricher just adds an additional ArraySchema to the array type (e. g. String[]) leading to a correct JSON array.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected static final String
    DEFAULT_SERVER_ERROR_RESPONSE
    The name of the exceptional response which becomes the default server error response.
    static final int
    DEFAULT_SERVER_ERROR_RESPONSE_CODE
    The status code of the exceptional response which becomes the default server error response.
    protected final Map<String,String>
    defValueRepl
    The map containing variables to replace in default values of schemas.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Enricher(Map<String,String> defValueRepl)
    Creates a new enricher for enriching the generated OpenAPI.

  • Method Summary

    Modifier and Type
    Method
    Description
    io.swagger.v3.oas.models.Operation
    addDeclaredResponses(io.swagger.v3.oas.models.Operation op, Method method, io.swagger.v3.oas.annotations.responses.ApiResponse[] classResponses, Function<io.swagger.v3.oas.annotations.responses.ApiResponse[],io.swagger.v3.oas.models.Operation> createOp)
    Adds the OperationResponses declared for the designated method and the default exceptional response to the designated operation and additionally enriches the schema of the designated default response with validation annotations as well as Default from the designated method.
    protected void
    applyDefaultResponseSchema(io.swagger.v3.oas.models.Operation op, io.swagger.v3.oas.models.media.Schema<?> defSchema, List<? extends de.aristaflow.adept2.model.communication.webservice.OperationResponse> declaredResponses)
    Applies the schema of the designated default response for to all responses that refer to it.
    protected void
    applyValidationAnnotations(Annotation[] annots, io.swagger.v3.oas.models.media.Schema<?> schema)
    Applies validation annotations (from javax.validation.constraints) as well as Default from the designated annotation collection to the designated schema.
    protected <T extends Annotation>
    T
    createAnnotationInstance(Class<T> annotClass, Map<String,Object> nonDefValues)
    Creates a new instance of the designated annotation class.
    protected Pair<Class<?>[],List<Class<?>>>
    distinguishClasses(Class<?>[] value)
    Distinguishes the classes from the designated array, that is, the first element will contain all normal classes and all Throwable which are (subclasses of) IlmExceptions.
    protected List<de.aristaflow.adept2.model.communication.webservice.OperationResponse>
    getDeclaredResponses(Method m)
    Gets all OperationResponses declared for the designated method as well as the default exceptional response, that is a response containing a plain IlmException with status code 5XX.
    protected String
    getDescription(String description, List<Class<?>> causedBy)
    Gets the description for a response declaration.
    protected Pair<io.swagger.v3.oas.annotations.responses.ApiResponse[],Boolean>
    joinResponses(Collection<? extends de.aristaflow.adept2.model.communication.webservice.OperationResponse> declaredResponses, String defMediaType, io.swagger.v3.oas.annotations.responses.ApiResponse[] classResponses)
    Creates instances of ApiResponse for the designated declared OperationResponses and joins them with the designated ApiResponses declared for the class.
    io.swagger.v3.oas.models.media.Schema
    resolve(io.swagger.v3.core.converter.AnnotatedType type, io.swagger.v3.core.converter.ModelConverterContext context, Iterator<io.swagger.v3.core.converter.ModelConverter> chain)
     

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface io.swagger.v3.core.converter.ModelConverter

    isOpenapi31

  • Field Details

    • DEFAULT_SERVER_ERROR_RESPONSE_CODE

      public static final int DEFAULT_SERVER_ERROR_RESPONSE_CODE
      The status code of the exceptional response which becomes the default server error response.
      See Also:

    • DEFAULT_SERVER_ERROR_RESPONSE

      protected static final String DEFAULT_SERVER_ERROR_RESPONSE
      The name of the exceptional response which becomes the default server error response.
      See Also:

    • defValueRepl

      protected final Map<String,String> defValueRepl
      The map containing variables to replace in default values of schemas.

  • Constructor Details

    • Enricher

      public Enricher(Map<String,String> defValueRepl)
      Creates a new enricher for enriching the generated OpenAPI.
      Parameters:
      defValueRepl - The map containing variables to replace in default values of schemas.

  • Method Details

    • addDeclaredResponses

      public io.swagger.v3.oas.models.Operation addDeclaredResponses(io.swagger.v3.oas.models.Operation op, Method method, io.swagger.v3.oas.annotations.responses.ApiResponse[] classResponses, Function<io.swagger.v3.oas.annotations.responses.ApiResponse[],io.swagger.v3.oas.models.Operation> createOp)
      Adds the OperationResponses declared for the designated method and the default exceptional response to the designated operation and additionally enriches the schema of the designated default response with validation annotations as well as Default from the designated method.
      Parameters:
      op - The operation to which to add the OperationResponses.
      method - The method implementing the operation and possibly providing OperationResponses.
      classResponses - The responses declared for the class. These will be added to the operation and the same mechanism will be used to add the OperationResponses.
      createOp - A function creating a new operation having the designated classResponses and the additionally declared and transformed OperationResponses as input.
      Returns:
      A new operation having the additional OperationResponses declared for the designated method.

    • getDeclaredResponses

      protected List<de.aristaflow.adept2.model.communication.webservice.OperationResponse> getDeclaredResponses(Method m)
      Gets all OperationResponses declared for the designated method as well as the default exceptional response, that is a response containing a plain IlmException with status code 5XX.
      Parameters:
      m - The method for which to get the declared OperationResponses.
      Returns:
      All OperationResponses declared for the designated method including the default exceptional response (5xx). This contains at least the default exceptional response.

    • applyDefaultResponseSchema

      protected void applyDefaultResponseSchema(io.swagger.v3.oas.models.Operation op, io.swagger.v3.oas.models.media.Schema<?> defSchema, List<? extends de.aristaflow.adept2.model.communication.webservice.OperationResponse> declaredResponses)
      Applies the schema of the designated default response for to all responses that refer to it.
      Parameters:
      op - The operation for which apply the default response schema.
      defSchema - The schema of the default response. If this is null the default schema is treated as null schema, that is, void.
      declaredResponses - The list of declared responses. Usages of the OperationResponse.DefaultResponsePlaceholder are searched within this list to replace the corresponding schema in the responses of the designated operation.
      See Also:
      • OperationResponse.DefaultResponsePlaceholder

    • joinResponses

      protected Pair<io.swagger.v3.oas.annotations.responses.ApiResponse[],Boolean> joinResponses(Collection<? extends de.aristaflow.adept2.model.communication.webservice.OperationResponse> declaredResponses, String defMediaType, io.swagger.v3.oas.annotations.responses.ApiResponse[] classResponses)
      Creates instances of ApiResponse for the designated declared OperationResponses and joins them with the designated ApiResponses declared for the class. This simply transforms the simple OperationResponses into the corresponding full-fledged ApiResponses. If an OperationResponse contains several types, these will be an Schema.oneOf() composed schema, that is, the response body will have only one of these types.
      Parameters:
      declaredResponses - The declared responses which to transform to ApiResponses. This must neither be null nor an empty collection.
      defMediaType - The media type of the default response.
      classResponses - The ApiResponses which are declared at the corresponding class. These will be added to the ApiResponses created for the designated OperationResponses.
      Returns:
      An array containing the designated ApiResponses from the class as well as the corresponding OperationResponses transformed appropriately. The second element of the pair indicates whether one declared response replaces the default response.
      See Also:
      • OperationResponse

    • distinguishClasses

      protected Pair<Class<?>[],List<Class<?>>> distinguishClasses(Class<?>[] value)
      Distinguishes the classes from the designated array, that is, the first element will contain all normal classes and all Throwable which are (subclasses of) IlmExceptions. Throwables which are not (subclasses of) de.aristaflow.ilm.util.Exception}s will be wrapped, that is, WrappingException will be added to the first element while the actual class of the Throwable will be added to the second element.
      At the end the first element will contain all classes that may be serialised while the second element will contain all Throwable classes that will be wrapped at runtime. The WrappingException will only be once it the first element even if there are several wrapped Throwables.
      Parameters:
      value - The classes declared by OperationResponse which need to be separated into real results and Throwables which will be wrapped at runtime.
      Returns:
      The classes declared by OperationResponse which are actually within the response and the Throwables that will be wrapped at runtime.

    • createAnnotationInstance

      protected <T extends Annotation> T createAnnotationInstance(Class<T> annotClass, Map<String,Object> nonDefValues)
      Creates a new instance of the designated annotation class. The designated map provides all values for the annotation instance that differ from the default values. It maps from field/method name to the corresponding value. Make sure that the value has the right type, which is the one defined in the annotation!
      Parameters:
      annotClass - The annotation class for which to create an instance.
      nonDefValues - The values for the annotation instance that differ from the default values of the annotation. This maps from field/method name to the corresponding value.
      Returns:
      A new instance (proxy) of the designated annotation class having the designated (non-default) values.

    • getDescription

      protected String getDescription(String description, List<Class<?>> causedBy)
      Gets the description for a response declaration. This is either the designated description or a generated description explaining the designated exceptions as causes for a WrappingException.
      Parameters:
      description - The description as declared by the OperationResponse.
      causedBy - The list of classes which are Throwables that will be wrapped at runtime.
      Returns:
      The designated description or a description explaining the designated causes for a wrapping exception.

    • applyValidationAnnotations

      protected void applyValidationAnnotations(Annotation[] annots, io.swagger.v3.oas.models.media.Schema<?> schema)
      Applies validation annotations (from javax.validation.constraints) as well as Default from the designated annotation collection to the designated schema.
      A minimal or maximal size will be set appropriately for normal and array schemas. The minimal size will be set to 1 in case of NotEmpty (and no explicit minimal size).
      Parameters:
      annots - The annotations which to apply to the designated schemas if they contain validation annotations. This may be null or empty.
      schema - The schema to which to apply validation annotations from the designated annotations. This may be null.

    • resolve

      public io.swagger.v3.oas.models.media.Schema resolve(io.swagger.v3.core.converter.AnnotatedType type, io.swagger.v3.core.converter.ModelConverterContext context, Iterator<io.swagger.v3.core.converter.ModelConverter> chain)
      Specified by:
      resolve in interface io.swagger.v3.core.converter.ModelConverter