Package org.openapitools.codegen

Class OpenAPINormalizer

  • public class OpenAPINormalizer
extends Object

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected org.slf4j.Logger LOGGER  
      protected io.swagger.v3.oas.models.OpenAPI openAPI  

    • Constructor Summary

      Constructors 
      Constructor Description
      OpenAPINormalizer​(io.swagger.v3.oas.models.OpenAPI openAPI, Map<String,​String> inputRules)
      Initializes OpenAPI Normalizer with a set of rules

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static OpenAPINormalizer createNormalizer​(io.swagger.v3.oas.models.OpenAPI openAPI, Map<String,​String> inputRules)
      Factory constructor for OpenAPINormalizer.
      void fixSelfReferenceSchema​(String name, io.swagger.v3.oas.models.media.Schema schema)
      Auto fix a self referencing schema using any type to replace the self-referencing sub-item.
      boolean getRule​(String ruleName)
      Get the rule.
      protected boolean isSelfReference​(String name, io.swagger.v3.oas.models.media.Schema subSchema)  
      protected void markSchemaAsVisited​(io.swagger.v3.oas.models.media.Schema schema, Set<io.swagger.v3.oas.models.media.Schema> visitedSchemas)
      Add the schema to the collection of visited schemas.
      protected void normalize()
      Normalizes the OpenAPI input, which may not perfectly conform to the specification.
      protected io.swagger.v3.oas.models.media.Schema normalizeAllOf​(io.swagger.v3.oas.models.media.Schema schema, Set<io.swagger.v3.oas.models.media.Schema> visitedSchemas)  
      protected io.swagger.v3.oas.models.media.Schema normalizeAllOfWithProperties​(io.swagger.v3.oas.models.media.Schema schema, Set<io.swagger.v3.oas.models.media.Schema> visitedSchemas)  
      protected io.swagger.v3.oas.models.media.Schema normalizeAnyOf​(io.swagger.v3.oas.models.media.Schema schema, Set<io.swagger.v3.oas.models.media.Schema> visitedSchemas)  
      protected io.swagger.v3.oas.models.media.Schema normalizeArraySchema​(io.swagger.v3.oas.models.media.Schema schema)  
      protected void normalizeBooleanSchema​(io.swagger.v3.oas.models.media.Schema schema, Set<io.swagger.v3.oas.models.media.Schema> visitedSchemas)  
      protected io.swagger.v3.oas.models.media.Schema normalizeComplexComposedSchema​(io.swagger.v3.oas.models.media.Schema schema, Set<io.swagger.v3.oas.models.media.Schema> visitedSchemas)  
      protected void normalizeComponentsResponses()
      Normalizes schemas in component's responses.
      protected void normalizeComponentsSchemas()
      Normalizes schemas in components
      protected void normalizeComponentsSecuritySchemes()
      Normalizes securitySchemes in components
      protected void normalizeContent​(io.swagger.v3.oas.models.media.Content content)
      Normalizes schemas in content
      protected void normalizeHeaders​(Map<String,​io.swagger.v3.oas.models.headers.Header> headers)
      Normalizes schemas in headers
      protected void normalizeInfo()
      Pre-populate info if it's not defined.
      protected void normalizeIntegerSchema​(io.swagger.v3.oas.models.media.Schema schema, Set<io.swagger.v3.oas.models.media.Schema> visitedSchemas)  
      protected io.swagger.v3.oas.models.media.Schema normalizeMapSchema​(io.swagger.v3.oas.models.media.Schema schema)  
      protected io.swagger.v3.oas.models.media.Schema normalizeOneOf​(io.swagger.v3.oas.models.media.Schema schema, Set<io.swagger.v3.oas.models.media.Schema> visitedSchemas)  
      protected void normalizeOperation​(io.swagger.v3.oas.models.Operation operation)
      Normalizes operation
      protected void normalizeParameters​(List<io.swagger.v3.oas.models.parameters.Parameter> parameters)
      Normalizes schemas in parameters
      protected void normalizePaths()
      Normalizes inline models in Paths
      protected void normalizeProperties​(Map<String,​io.swagger.v3.oas.models.media.Schema> properties, Set<io.swagger.v3.oas.models.media.Schema> visitedSchemas)  
      protected void normalizeRequestBody​(io.swagger.v3.oas.models.Operation operation)
      Normalizes schemas in RequestBody
      protected void normalizeResponse​(io.swagger.v3.oas.models.responses.ApiResponse apiResponse)
      Normalizes schemas in ApiResponse
      protected void normalizeResponses​(io.swagger.v3.oas.models.Operation operation)
      Normalizes schemas in ApiResponses
      io.swagger.v3.oas.models.media.Schema normalizeSchema​(io.swagger.v3.oas.models.media.Schema schema, Set<io.swagger.v3.oas.models.media.Schema> visitedSchemas)
      Normalizes a schema
      protected io.swagger.v3.oas.models.media.Schema normalizeSimpleSchema​(io.swagger.v3.oas.models.media.Schema schema, Set<io.swagger.v3.oas.models.media.Schema> visitedSchemas)  
      protected void processAddUnsignedToIntegerWithInvalidMaxValue​(io.swagger.v3.oas.models.media.Schema schema)
      If the schema is integer and the max value is invalid (out of bound) then add x-unsigned to use unsigned integer/long instead.
      protected void processFixDuplicatedOperationId​(io.swagger.v3.oas.models.Operation operation)  
      protected void processKeepOnlyFirstTagInOperation​(io.swagger.v3.oas.models.Operation operation)
      Keep only first tag in the operation if the operation has more than one tag.
      protected io.swagger.v3.oas.models.media.Schema processNormalize31Spec​(io.swagger.v3.oas.models.media.Schema schema, Set<io.swagger.v3.oas.models.media.Schema> visitedSchemas)
      When set to true, normalize schema so that it works well with the generator.
      protected io.swagger.v3.oas.models.media.Schema processRefactorAllOfWithPropertiesOnly​(io.swagger.v3.oas.models.media.Schema schema)
      When set to true, refactor schema with allOf and properties in the same level to a schema with allOf only and the allOf contains a new schema containing the properties in the top level.
      protected void processRemoveAnyOfOneOfAndKeepPropertiesOnly​(io.swagger.v3.oas.models.media.Schema schema)
      If the schema contains anyOf/oneOf and properties, remove oneOf/anyOf as these serve as rules to ensure inter-dependency between properties.
      protected void processRemoveXInternalFromOperation​(io.swagger.v3.oas.models.Operation operation)
      Remove/hide the x-internal in operations and model.
      void processRules​(Map<String,​String> inputRules)
      Process the rules.
      protected io.swagger.v3.oas.models.media.Schema processSetArraytoNullable​(io.swagger.v3.oas.models.media.Schema schema)
      Set nullable to true in array/set if needed.
      protected io.swagger.v3.oas.models.media.Schema processSetMapToNullable​(io.swagger.v3.oas.models.media.Schema schema)
      Set nullable to true in map if needed.
      protected io.swagger.v3.oas.models.media.Schema processSetPrimitiveTypesToNullable​(io.swagger.v3.oas.models.media.Schema schema)
      Set nullable to true in primitive types (e.g. string) if needed.
      protected void processSetTagsForAllOperations​(io.swagger.v3.oas.models.Operation operation)
      Set the tag name for all operations
      protected void processSetTagsToOperationId​(io.swagger.v3.oas.models.Operation operation)
      Set the tag name to operationId (or "default" if operationId is empty)
      protected void processSetTagsToVendorExtension​(io.swagger.v3.oas.models.Operation operation)
      Set the tag name to the value of the provided vendor extension
      protected io.swagger.v3.oas.models.media.Schema processSimplifyAnyOf​(io.swagger.v3.oas.models.media.Schema schema)
      If the schema is anyOf and the sub-schemas is null, set `nullable: true` instead.
      protected io.swagger.v3.oas.models.media.Schema processSimplifyAnyOfStringAndEnumString​(io.swagger.v3.oas.models.media.Schema schema)
      If the schema is anyOf and the sub-schemas are either string or enum of string, then simplify it to just enum of string as many generators do not yet support anyOf.
      protected void processSimplifyBooleanEnum​(io.swagger.v3.oas.models.media.Schema schema)
      If the schema is boolean and its enum is defined, then simply it to just boolean.
      protected io.swagger.v3.oas.models.media.Schema processSimplifyOneOf​(io.swagger.v3.oas.models.media.Schema schema)
      If the schema is oneOf and the sub-schemas is null, set `nullable: true` instead.
      protected void processUseAllOfRefAsParent​(io.swagger.v3.oas.models.media.Schema schema)
      Child schemas in `allOf` is considered a parent if it's a `$ref` (instead of inline schema).
      protected void refactorAllOfWithMetadataOnlySchemas​(io.swagger.v3.oas.models.media.Schema schema)  
      protected void removeUnsupportedSchemasFromAllOf​(io.swagger.v3.oas.models.media.Schema schema)  
      protected io.swagger.v3.oas.models.media.Schema setNullable​(io.swagger.v3.oas.models.media.Schema schema)  
      protected boolean skipNormalization​(io.swagger.v3.oas.models.media.Schema schema, Set<io.swagger.v3.oas.models.media.Schema> visitedSchemas)
      Check if normalization is needed.

    • Field Detail

      • openAPI

        protected io.swagger.v3.oas.models.OpenAPI openAPI

      • LOGGER

        protected final org.slf4j.Logger LOGGER

    • Constructor Detail

      • OpenAPINormalizer

        public OpenAPINormalizer​(io.swagger.v3.oas.models.OpenAPI openAPI,
                         Map<String,​String> inputRules)
        Initializes OpenAPI Normalizer with a set of rules
        Parameters:
        openAPI - OpenAPI
        inputRules - a map of rules

    • Method Detail

      • createNormalizer

        public static OpenAPINormalizer createNormalizer​(io.swagger.v3.oas.models.OpenAPI openAPI,
                                                 Map<String,​String> inputRules)
        Factory constructor for OpenAPINormalizer. Default can be overriden by setting the NORMALIZER_CLASS rule

      • getRule

        public boolean getRule​(String ruleName)
        Get the rule.
        Parameters:
        ruleName - the name of the rule
        Returns:
        true if the rule is set

      • processRules

        public void processRules​(Map<String,​String> inputRules)
        Process the rules.
        Parameters:
        inputRules - a map of rules

      • normalize

        protected void normalize()
        Normalizes the OpenAPI input, which may not perfectly conform to the specification.

      • normalizeInfo

        protected void normalizeInfo()
        Pre-populate info if it's not defined.

      • normalizePaths

        protected void normalizePaths()
        Normalizes inline models in Paths

      • normalizeOperation

        protected void normalizeOperation​(io.swagger.v3.oas.models.Operation operation)
        Normalizes operation
        Parameters:
        operation - Operation

      • normalizeContent

        protected void normalizeContent​(io.swagger.v3.oas.models.media.Content content)
        Normalizes schemas in content
        Parameters:
        content - target content

      • normalizeRequestBody

        protected void normalizeRequestBody​(io.swagger.v3.oas.models.Operation operation)
        Normalizes schemas in RequestBody
        Parameters:
        operation - target operation

      • normalizeParameters

        protected void normalizeParameters​(List<io.swagger.v3.oas.models.parameters.Parameter> parameters)
        Normalizes schemas in parameters
        Parameters:
        parameters - List parameters

      • normalizeResponses

        protected void normalizeResponses​(io.swagger.v3.oas.models.Operation operation)
        Normalizes schemas in ApiResponses
        Parameters:
        operation - target operation

      • normalizeResponse

        protected void normalizeResponse​(io.swagger.v3.oas.models.responses.ApiResponse apiResponse)
        Normalizes schemas in ApiResponse
        Parameters:
        apiResponse - API response

      • normalizeHeaders

        protected void normalizeHeaders​(Map<String,​io.swagger.v3.oas.models.headers.Header> headers)
        Normalizes schemas in headers
        Parameters:
        headers - a map of headers

      • normalizeComponentsSecuritySchemes

        protected void normalizeComponentsSecuritySchemes()
        Normalizes securitySchemes in components

      • normalizeComponentsSchemas

        protected void normalizeComponentsSchemas()
        Normalizes schemas in components

      • normalizeComponentsResponses

        protected void normalizeComponentsResponses()
        Normalizes schemas in component's responses.

      • fixSelfReferenceSchema

        public void fixSelfReferenceSchema​(String name,
                                   io.swagger.v3.oas.models.media.Schema schema)
        Auto fix a self referencing schema using any type to replace the self-referencing sub-item.
        Parameters:
        name - Schema name
        schema - Schema

      • isSelfReference

        protected boolean isSelfReference​(String name,
                                  io.swagger.v3.oas.models.media.Schema subSchema)

      • normalizeSchema

        public io.swagger.v3.oas.models.media.Schema normalizeSchema​(io.swagger.v3.oas.models.media.Schema schema,
                                                             Set<io.swagger.v3.oas.models.media.Schema> visitedSchemas)
        Normalizes a schema
        Parameters:
        schema - Schema
        visitedSchemas - a set of visited schemas
        Returns:
        Schema

      • skipNormalization

        protected boolean skipNormalization​(io.swagger.v3.oas.models.media.Schema schema,
                                    Set<io.swagger.v3.oas.models.media.Schema> visitedSchemas)
        Check if normalization is needed. No normalization needed if the schema is null or is a $ref or already processed.
        Parameters:
        schema - Schema
        visitedSchemas - a set of visited schemas
        Returns:
        false if normalization is needed

      • markSchemaAsVisited

        protected void markSchemaAsVisited​(io.swagger.v3.oas.models.media.Schema schema,
                                   Set<io.swagger.v3.oas.models.media.Schema> visitedSchemas)
        Add the schema to the collection of visited schemas.
        Parameters:
        schema - schema to add
        visitedSchemas - current visited schemas

      • normalizeArraySchema

        protected io.swagger.v3.oas.models.media.Schema normalizeArraySchema​(io.swagger.v3.oas.models.media.Schema schema)

      • normalizeMapSchema

        protected io.swagger.v3.oas.models.media.Schema normalizeMapSchema​(io.swagger.v3.oas.models.media.Schema schema)

      • normalizeSimpleSchema

        protected io.swagger.v3.oas.models.media.Schema normalizeSimpleSchema​(io.swagger.v3.oas.models.media.Schema schema,
                                                                      Set<io.swagger.v3.oas.models.media.Schema> visitedSchemas)

      • normalizeBooleanSchema

        protected void normalizeBooleanSchema​(io.swagger.v3.oas.models.media.Schema schema,
                                      Set<io.swagger.v3.oas.models.media.Schema> visitedSchemas)

      • normalizeIntegerSchema

        protected void normalizeIntegerSchema​(io.swagger.v3.oas.models.media.Schema schema,
                                      Set<io.swagger.v3.oas.models.media.Schema> visitedSchemas)

      • normalizeProperties

        protected void normalizeProperties​(Map<String,​io.swagger.v3.oas.models.media.Schema> properties,
                                   Set<io.swagger.v3.oas.models.media.Schema> visitedSchemas)

      • refactorAllOfWithMetadataOnlySchemas

        protected void refactorAllOfWithMetadataOnlySchemas​(io.swagger.v3.oas.models.media.Schema schema)

      • removeUnsupportedSchemasFromAllOf

        protected void removeUnsupportedSchemasFromAllOf​(io.swagger.v3.oas.models.media.Schema schema)

      • normalizeAllOf

        protected io.swagger.v3.oas.models.media.Schema normalizeAllOf​(io.swagger.v3.oas.models.media.Schema schema,
                                                               Set<io.swagger.v3.oas.models.media.Schema> visitedSchemas)

      • normalizeAllOfWithProperties

        protected io.swagger.v3.oas.models.media.Schema normalizeAllOfWithProperties​(io.swagger.v3.oas.models.media.Schema schema,
                                                                             Set<io.swagger.v3.oas.models.media.Schema> visitedSchemas)

      • normalizeOneOf

        protected io.swagger.v3.oas.models.media.Schema normalizeOneOf​(io.swagger.v3.oas.models.media.Schema schema,
                                                               Set<io.swagger.v3.oas.models.media.Schema> visitedSchemas)

      • normalizeAnyOf

        protected io.swagger.v3.oas.models.media.Schema normalizeAnyOf​(io.swagger.v3.oas.models.media.Schema schema,
                                                               Set<io.swagger.v3.oas.models.media.Schema> visitedSchemas)

      • normalizeComplexComposedSchema

        protected io.swagger.v3.oas.models.media.Schema normalizeComplexComposedSchema​(io.swagger.v3.oas.models.media.Schema schema,
                                                                               Set<io.swagger.v3.oas.models.media.Schema> visitedSchemas)

      • processUseAllOfRefAsParent

        protected void processUseAllOfRefAsParent​(io.swagger.v3.oas.models.media.Schema schema)
        Child schemas in `allOf` is considered a parent if it's a `$ref` (instead of inline schema).
        Parameters:
        schema - Schema

      • processRemoveXInternalFromOperation

        protected void processRemoveXInternalFromOperation​(io.swagger.v3.oas.models.Operation operation)
        Remove/hide the x-internal in operations and model.
        Parameters:
        operation - Operation

      • processKeepOnlyFirstTagInOperation

        protected void processKeepOnlyFirstTagInOperation​(io.swagger.v3.oas.models.Operation operation)
        Keep only first tag in the operation if the operation has more than one tag.
        Parameters:
        operation - Operation

      • processSetTagsForAllOperations

        protected void processSetTagsForAllOperations​(io.swagger.v3.oas.models.Operation operation)
        Set the tag name for all operations
        Parameters:
        operation - Operation

      • processSetTagsToOperationId

        protected void processSetTagsToOperationId​(io.swagger.v3.oas.models.Operation operation)
        Set the tag name to operationId (or "default" if operationId is empty)
        Parameters:
        operation - Operation

      • processSetTagsToVendorExtension

        protected void processSetTagsToVendorExtension​(io.swagger.v3.oas.models.Operation operation)
        Set the tag name to the value of the provided vendor extension
        Parameters:
        operation - Operation

      • processFixDuplicatedOperationId

        protected void processFixDuplicatedOperationId​(io.swagger.v3.oas.models.Operation operation)

      • processRemoveAnyOfOneOfAndKeepPropertiesOnly

        protected void processRemoveAnyOfOneOfAndKeepPropertiesOnly​(io.swagger.v3.oas.models.media.Schema schema)
        If the schema contains anyOf/oneOf and properties, remove oneOf/anyOf as these serve as rules to ensure inter-dependency between properties. It's a workaround as such validation is not supported at the moment.
        Parameters:
        schema - Schema

      • processSimplifyAnyOfStringAndEnumString

        protected io.swagger.v3.oas.models.media.Schema processSimplifyAnyOfStringAndEnumString​(io.swagger.v3.oas.models.media.Schema schema)
        If the schema is anyOf and the sub-schemas are either string or enum of string, then simplify it to just enum of string as many generators do not yet support anyOf.
        Parameters:
        schema - Schema
        Returns:
        Schema

      • processSimplifyOneOf

        protected io.swagger.v3.oas.models.media.Schema processSimplifyOneOf​(io.swagger.v3.oas.models.media.Schema schema)
        If the schema is oneOf and the sub-schemas is null, set `nullable: true` instead. If there's only one sub-schema, simply return the sub-schema directly.
        Parameters:
        schema - Schema
        Returns:
        Schema

      • processSetArraytoNullable

        protected io.swagger.v3.oas.models.media.Schema processSetArraytoNullable​(io.swagger.v3.oas.models.media.Schema schema)
        Set nullable to true in array/set if needed.
        Parameters:
        schema - Schema
        Returns:
        Schema

      • processSetPrimitiveTypesToNullable

        protected io.swagger.v3.oas.models.media.Schema processSetPrimitiveTypesToNullable​(io.swagger.v3.oas.models.media.Schema schema)
        Set nullable to true in primitive types (e.g. string) if needed.
        Parameters:
        schema - Schema
        Returns:
        Schema

      • setNullable

        protected io.swagger.v3.oas.models.media.Schema setNullable​(io.swagger.v3.oas.models.media.Schema schema)

      • processSetMapToNullable

        protected io.swagger.v3.oas.models.media.Schema processSetMapToNullable​(io.swagger.v3.oas.models.media.Schema schema)
        Set nullable to true in map if needed.
        Parameters:
        schema - Schema
        Returns:
        Schema

      • processSimplifyAnyOf

        protected io.swagger.v3.oas.models.media.Schema processSimplifyAnyOf​(io.swagger.v3.oas.models.media.Schema schema)
        If the schema is anyOf and the sub-schemas is null, set `nullable: true` instead. If there's only one sub-schema, simply return the sub-schema directly.
        Parameters:
        schema - Schema
        Returns:
        Schema

      • processSimplifyBooleanEnum

        protected void processSimplifyBooleanEnum​(io.swagger.v3.oas.models.media.Schema schema)
        If the schema is boolean and its enum is defined, then simply it to just boolean.
        Parameters:
        schema - Schema

      • processAddUnsignedToIntegerWithInvalidMaxValue

        protected void processAddUnsignedToIntegerWithInvalidMaxValue​(io.swagger.v3.oas.models.media.Schema schema)
        If the schema is integer and the max value is invalid (out of bound) then add x-unsigned to use unsigned integer/long instead.
        Parameters:
        schema - Schema

      • processRefactorAllOfWithPropertiesOnly

        protected io.swagger.v3.oas.models.media.Schema processRefactorAllOfWithPropertiesOnly​(io.swagger.v3.oas.models.media.Schema schema)
        When set to true, refactor schema with allOf and properties in the same level to a schema with allOf only and the allOf contains a new schema containing the properties in the top level.
        Parameters:
        schema - Schema
        Returns:
        Schema

      • processNormalize31Spec

        protected io.swagger.v3.oas.models.media.Schema processNormalize31Spec​(io.swagger.v3.oas.models.media.Schema schema,
                                                                       Set<io.swagger.v3.oas.models.media.Schema> visitedSchemas)
        When set to true, normalize schema so that it works well with the generator.
        Parameters:
        schema - Schema
        visitedSchemas - a set of visited schemas
        Returns:
        Schema