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

Class OpenApiReader

  • All Implemented Interfaces:
    io.swagger.v3.oas.integration.api.OpenApiReader
    public class OpenApiReader
extends io.swagger.v3.jaxrs2.Reader
    The reader for creating the OpenAPI model. This reader adds additional logic when creating the OpenAPI model. These are:
    • Operations get the name of the corresponding (sub) resource as tag. This improves separation of operations.
    • Add external documentation to the service and each operation. The links refer to the corresponding class and methods within the Javadoc. The javadoc is provided via a javadoc servlet so the links work.
    • Adds a description for implicit header data, e. g. API version and session token data to the appropriate operations.
    • It enriches parameters, return values and types with additional validation constraints besides the ones considered by Swagger within ParameterProcessor as well as Default.
    • It adds responses declared additionally via OperationResponse to the corresponding operations for media type MediaType.APPLICATION_JSON.
    • It will change the generated default response to become the response with status code HttpURLConnection.HTTP_OK (or HttpURLConnection.HTTP_NO_CONTENT))if there is no declared response with this status code. Otherwise the generated default response will just be removed.
    • It adds a new error response with status code "5XX" containing an IlmException so that arbitrary exceptions may the returned.
    • It adds callbacks declared via Callback to the corresponding operations.
    • It allows for sorting all elements alphabetically. This simplifies comparing different versions of a generated API.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected int apiLevel
      The API level for the current request.
      protected Enricher enricher
      The enricher for adding restrictions stemming from validation annotations and adding exceptional responses if declared.
      protected String javadocServletBaseUrl
      The URL of the Javadoc servlet to set the documentation references properly.
      protected static AtomicBoolean MODEL_CONVERTER_REGISTERED
      Whether a model converter setting default values in the schema has been registered.
      protected boolean sorted
      Whether to return the OpenAPI sorted.
      protected Map<String,​String> subResTags
      The tags for sub resources set for operations.

      • Fields inherited from class io.swagger.v3.jaxrs2.Reader

        config, DEFAULT_DESCRIPTION, DEFAULT_MEDIA_TYPE_VALUE

    • Constructor Summary

      Constructors 
      Constructor Description
      OpenApiReader()  
      OpenApiReader​(io.swagger.v3.oas.integration.api.OpenAPIConfiguration openApiConfiguration)  
      OpenApiReader​(io.swagger.v3.oas.models.OpenAPI openAPI)  

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected void adaptOperation​(Method m, io.swagger.v3.oas.models.Operation o)
      Adapts the designated operation stemming from the designated method.
      protected void addCallbacks​(Method method, io.swagger.v3.oas.models.Operation o)
      Checks for whether the designated method declares a Callback parameter and if so, adds the corresponding callback interface to the designated operation.
      protected io.swagger.v3.oas.models.Operation parseMethod​(Class<?> cls, Method method, List<io.swagger.v3.oas.models.parameters.Parameter> globalParameters, javax.ws.rs.Produces methodProduces, javax.ws.rs.Produces classProduces, javax.ws.rs.Consumes methodConsumes, javax.ws.rs.Consumes classConsumes, List<io.swagger.v3.oas.models.security.SecurityRequirement> classSecurityRequirements, Optional<io.swagger.v3.oas.models.ExternalDocumentation> classExternalDocs, Set<String> classTags, List<io.swagger.v3.oas.models.servers.Server> classServers, boolean isSubresource, io.swagger.v3.oas.models.parameters.RequestBody parentRequestBody, io.swagger.v3.oas.models.responses.ApiResponses parentResponses, com.fasterxml.jackson.annotation.JsonView jsonViewAnnotation, io.swagger.v3.oas.annotations.responses.ApiResponse[] classResponses, com.fasterxml.jackson.databind.introspect.AnnotatedMethod annotatedMethod)  
      io.swagger.v3.oas.models.OpenAPI read​(Class<?> cls, String parentPath, String parentMethod, boolean isSubresource, io.swagger.v3.oas.models.parameters.RequestBody parentRequestBody, io.swagger.v3.oas.models.responses.ApiResponses parentResponses, Set<String> parentTags, List<io.swagger.v3.oas.models.parameters.Parameter> parentParameters, Set<Class<?>> scannedResources)  
      io.swagger.v3.oas.models.OpenAPI read​(Set<Class<?>> classes, Map<String,​Object> resources)  
      protected void removeStringTypeFromCompSchema​(io.swagger.v3.oas.models.responses.ApiResponses responses)
      Removes the type string from every schema of the designated responses in case it is a composed schema.
      protected boolean requiredApiLevel​(Method m)
      Gets whether the designated method is required for the currently requested API level.
      void setApplication​(javax.ws.rs.core.Application app)
      Sets the application and retrieves various configurations from the resource config.
      protected void setExtDocUrl​(Supplier<io.swagger.v3.oas.models.ExternalDocumentation> extDocSupp, Consumer<io.swagger.v3.oas.models.ExternalDocumentation> extDocCons, Supplier<String> javadocRefString)
      Sets the external reference to the corresponding javadoc.
      protected void setHeaderDataDescription​(Method m, io.swagger.v3.oas.models.Operation o)
      Sets a description referring to the header data operation providing information on the implicit header data expected at most methods.
      protected void setTag​(Method m, io.swagger.v3.oas.models.Operation o)
      Sets the tag of the operation appropriately to the resource of the designated method.
      protected static <T> Map<String,​T> sort​(Map<String,​T> map)
      Sorts the entries in the designated map.

      • Methods inherited from class io.swagger.v3.jaxrs2.Reader

        applyPathParamsPatterns, getOpenAPI, getOperationId, getParameters, getParametersListFromAnnotation, getSubResourceWithJaxRsSubresourceLocatorSpecs, ignoreOperationPath, ignoreOperationPathStrict, isMethodOverridden, isOperationHidden, parseMethod, parseMethod, parseMethod, processContent, processRequestBody, read, read, resolveApplicationPath, resolveEmptyContent, resolveResponseSchemaFromReturnType, setConfiguration

    • Field Detail

      • MODEL_CONVERTER_REGISTERED

        protected static final AtomicBoolean MODEL_CONVERTER_REGISTERED
        Whether a model converter setting default values in the schema has been registered.
        Since model converters are registered at a static singleton, they should only registered once, not per instance of the OpenAPIReader.

      • apiLevel

        protected int apiLevel
        The API level for the current request. The generated OpenAPI will only contain the API for this and lower levels.

      • sorted

        protected boolean sorted
        Whether to return the OpenAPI sorted. This allows for comparing different versions of the same OpenAPI.

      • javadocServletBaseUrl

        protected String javadocServletBaseUrl
        The URL of the Javadoc servlet to set the documentation references properly.

      • enricher

        protected Enricher enricher
        The enricher for adding restrictions stemming from validation annotations and adding exceptional responses if declared.

      • subResTags

        protected final Map<String,​String> subResTags
        The tags for sub resources set for operations.

    • Constructor Detail

      • OpenApiReader

        public OpenApiReader()

      • OpenApiReader

        public OpenApiReader​(io.swagger.v3.oas.models.OpenAPI openAPI)

      • OpenApiReader

        public OpenApiReader​(io.swagger.v3.oas.integration.api.OpenAPIConfiguration openApiConfiguration)

    • Method Detail

      • setApplication

        public void setApplication​(javax.ws.rs.core.Application app)
        Sets the application and retrieves various configurations from the resource config.
        Overrides:
        setApplication in class io.swagger.v3.jaxrs2.Reader

      • read

        public io.swagger.v3.oas.models.OpenAPI read​(Set<Class<?>> classes,
                                             Map<String,​Object> resources)
        Specified by:
        read in interface io.swagger.v3.oas.integration.api.OpenApiReader
        Overrides:
        read in class io.swagger.v3.jaxrs2.Reader

      • read

        public io.swagger.v3.oas.models.OpenAPI read​(Class<?> cls,
                                             String parentPath,
                                             String parentMethod,
                                             boolean isSubresource,
                                             io.swagger.v3.oas.models.parameters.RequestBody parentRequestBody,
                                             io.swagger.v3.oas.models.responses.ApiResponses parentResponses,
                                             Set<String> parentTags,
                                             List<io.swagger.v3.oas.models.parameters.Parameter> parentParameters,
                                             Set<Class<?>> scannedResources)
        Overrides:
        read in class io.swagger.v3.jaxrs2.Reader

      • parseMethod

        protected io.swagger.v3.oas.models.Operation parseMethod​(Class<?> cls,
                                                         Method method,
                                                         List<io.swagger.v3.oas.models.parameters.Parameter> globalParameters,
                                                         javax.ws.rs.Produces methodProduces,
                                                         javax.ws.rs.Produces classProduces,
                                                         javax.ws.rs.Consumes methodConsumes,
                                                         javax.ws.rs.Consumes classConsumes,
                                                         List<io.swagger.v3.oas.models.security.SecurityRequirement> classSecurityRequirements,
                                                         Optional<io.swagger.v3.oas.models.ExternalDocumentation> classExternalDocs,
                                                         Set<String> classTags,
                                                         List<io.swagger.v3.oas.models.servers.Server> classServers,
                                                         boolean isSubresource,
                                                         io.swagger.v3.oas.models.parameters.RequestBody parentRequestBody,
                                                         io.swagger.v3.oas.models.responses.ApiResponses parentResponses,
                                                         com.fasterxml.jackson.annotation.JsonView jsonViewAnnotation,
                                                         io.swagger.v3.oas.annotations.responses.ApiResponse[] classResponses,
                                                         com.fasterxml.jackson.databind.introspect.AnnotatedMethod annotatedMethod)
        Overrides:
        parseMethod in class io.swagger.v3.jaxrs2.Reader

      • requiredApiLevel

        protected boolean requiredApiLevel​(Method m)
        Gets whether the designated method is required for the currently requested API level. This considers the method, then the return value and then the declaring class of the method. The first declared ApiLevel counts.
        Parameters:
        m - The method which to check for whether it is required for the currently requested API level.
        Returns:
        Whether the designated method is required for the currently requested API level.

      • setTag

        protected void setTag​(Method m,
                      io.swagger.v3.oas.models.Operation o)
        Sets the tag of the operation appropriately to the resource of the designated method. This allows to easily distinguish multiple methods with the same name in different sub resources.
        Parameters:
        m - The method for which to set the tag.
        o - The operation in which to adapt the tag.

      • setExtDocUrl

        protected void setExtDocUrl​(Supplier<io.swagger.v3.oas.models.ExternalDocumentation> extDocSupp,
                            Consumer<io.swagger.v3.oas.models.ExternalDocumentation> extDocCons,
                            Supplier<String> javadocRefString)
        Sets the external reference to the corresponding javadoc. The javadoc reference will be the base URL of the javadoc servlet appended with the string returned by the javadoc supplier, which is either a string for a class or a method.
        Parameters:
        extDocSupp - The supplier for the external documentation which to adapt. This must not be null, but it may return null. If it supplies null, a new instance of ExternalDocumentation will be created and set via the designated consumer.
        extDocCons - The consumer for accepting a new external documentation which does not exist yet. This must not be null. It will only be used in case no external documentation exists yet.
        javadocRefString - The supplier creating a string for a class or a method to be used as javadoc reference.

      • setHeaderDataDescription

        protected void setHeaderDataDescription​(Method m,
                                        io.swagger.v3.oas.models.Operation o)
        Sets a description referring to the header data operation providing information on the implicit header data expected at most methods. This includes the accepted API version as well as session token data where appropriate.

        Note that the operation has no parameters here yet. So we need to go over the method to detect whether the method has a session token or not.

        Parameters:
        m - The method for which to add a description for the implicit header data.
        o - The operation to which to optionally add a description for the implicit header data.

      • removeStringTypeFromCompSchema

        protected void removeStringTypeFromCompSchema​(io.swagger.v3.oas.models.responses.ApiResponses responses)
        Removes the type string from every schema of the designated responses in case it is a composed schema.
        This has been requested to be changed with a pull request.
        Parameters:
        responses - The responses in which to unset the string type in all composed schemas.

      • addCallbacks

        protected void addCallbacks​(Method method,
                            io.swagger.v3.oas.models.Operation o)
        Checks for whether the designated method declares a Callback parameter and if so, adds the corresponding callback interface to the designated operation.
        Parameters:
        method - The method which to check for Callback parameters.
        o - The operation to which to add the corresponding callbacks.

      • sort

        protected static <T> Map<String,​T> sort​(Map<String,​T> map)
        Sorts the entries in the designated map. If the designated map is a LinkedHashMap the entries will be sorted within it. Otherwise a new LinkedHashMap will be returned.
        Parameters:
        map - The map containing the entries to sort. This may be null.
        Returns:
        A map containing the entries in alphabetical order. This is the same map as the designated one in case the designated one is a LinkedHashMap. This will be null if the designated map is null.