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

Class OpenApiReader

java.lang.Object
io.swagger.v3.jaxrs2.Reader
de.aristaflow.ilm.ws.rest.base.service.openapi.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 final 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 final 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

    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, jakarta.ws.rs.Produces methodProduces, jakarta.ws.rs.Produces classProduces, jakarta.ws.rs.Consumes methodConsumes, jakarta.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(jakarta.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, getComponents, getOpenAPI, getOpenApiTags, getOperationId, getParameters, getParametersListFromAnnotation, getPaths, getSubResourceWithJaxRsSubresourceLocatorSpecs, ignoreOperationPath, ignoreOperationPathStrict, isMethodOverridden, isOperationHidden, parseMethod, parseMethod, parseMethod, processContent, processRequestBody, read, read, resolveApplicationPath, resolveEmptyContent, resolveResponseSchemaFromReturnType, setConfiguration, setOperationObjectFromApiOperationAnnotation

    Methods inherited from class java.lang.Object

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

  • Field Details

    • 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 Details

    • 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 Details

    • setApplication

      public void setApplication(jakarta.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, jakarta.ws.rs.Produces methodProduces, jakarta.ws.rs.Produces classProduces, jakarta.ws.rs.Consumes methodConsumes, jakarta.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.

    • adaptOperation

      protected void adaptOperation(Method m, io.swagger.v3.oas.models.Operation o)
      Adapts the designated operation stemming from the designated method. This will setTag(Method, Operation), setExtDocUrl(Supplier, Consumer, Supplier), removeStringTypeFromCompSchema(ApiResponses) and addCallbacks(Method, Operation).
      Parameters:
      m - The method for which to adapt the corresponding operation.
      o - The operation which to adapt.

    • 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.