Invalid swagger specification 2.0?

tomcruise81 commented 3 years ago

Utilizing the swagger specs available at https://github.com/SoftwareAG/webmethods-api-gateway/tree/master/apigatewayservices, I'm trying to generate a Golang client via https://github.com/go-swagger/go-swagger

For https://github.com/SoftwareAG/webmethods-api-gateway/blob/master/apigatewayservices/APIGatewayServiceManagement.json, I get the following output:

validating spec APIGatewayServiceManagement.json
The swagger spec at "APIGatewayServiceManagement.json" is invalid against swagger specification 2.0. see errors :
- "paths./tracer/{correlationID}.get.responses.200" must validate one and only one schema (oneOf). Found none valid
- "paths./tracer/{correlationID}.get.responses.200.schema" must validate one and only one schema (oneOf). Found none valid
- "paths./tracer/{correlationID}.get.responses.200.schema.additionalProperties" must validate at least one schema (anyOf)
- "paths./tracer/{correlationID}.get.responses.200.schema.additionalProperties.items" must validate at least one schema (anyOf)
- paths./tracer/{correlationID}.get.responses.200.schema.additionalProperties.items.originalRef in body is a forbidden property
- "definitions.ImportTraceInfoResponse.properties.traceInfo.items" must validate at least one schema (anyOf)
- "definitions.ImportTraceInfoResponse.properties.traceInfo.items.additionalProperties" must validate at least one schema (anyOf)
- "definitions.ImportTraceInfoResponse.properties.traceInfo.items.additionalProperties.items" must validate at least one schema (anyOf)
- definitions.ImportTraceInfoResponse.properties.traceInfo.items.additionalProperties.items.originalRef in body is a forbidden property
- "definitions.GqlSDLDefinitions.properties.objectTypeExtensions.additionalProperties" must validate at least one schema (anyOf)
- "definitions.GqlSDLDefinitions.properties.objectTypeExtensions.additionalProperties.items" must validate at least one schema (anyOf)
- definitions.GqlSDLDefinitions.properties.objectTypeExtensions.additionalProperties.items.originalRef in body is a forbidden property
- "definitions.GqlSDLDefinitions.properties.enumTypeExtensions.additionalProperties" must validate at least one schema (anyOf)
- "definitions.GqlSDLDefinitions.properties.enumTypeExtensions.additionalProperties.items" must validate at least one schema (anyOf)
- definitions.GqlSDLDefinitions.properties.enumTypeExtensions.additionalProperties.items.originalRef in body is a forbidden property
- "definitions.GqlSDLDefinitions.properties.interfaceTypeExtensions.additionalProperties" must validate at least one schema (anyOf)
- "definitions.GqlSDLDefinitions.properties.interfaceTypeExtensions.additionalProperties.items" must validate at least one schema (anyOf)
- definitions.GqlSDLDefinitions.properties.interfaceTypeExtensions.additionalProperties.items.originalRef in body is a forbidden property
- "definitions.GqlSDLDefinitions.properties.scalarTypeExtensions.additionalProperties" must validate at least one schema (anyOf)
- "definitions.GqlSDLDefinitions.properties.scalarTypeExtensions.additionalProperties.items" must validate at least one schema (anyOf)
- definitions.GqlSDLDefinitions.properties.scalarTypeExtensions.additionalProperties.items.originalRef in body is a forbidden property
- "definitions.GqlSDLDefinitions.properties.unionTypeExtensions.additionalProperties" must validate at least one schema (anyOf)
- "definitions.GqlSDLDefinitions.properties.unionTypeExtensions.additionalProperties.items" must validate at least one schema (anyOf)
- definitions.GqlSDLDefinitions.properties.unionTypeExtensions.additionalProperties.items.originalRef in body is a forbidden property
- "definitions.GqlSDLDefinitions.properties.inputObjectTypeExtensions.additionalProperties" must validate at least one schema (anyOf)
- "definitions.GqlSDLDefinitions.properties.inputObjectTypeExtensions.additionalProperties.items" must validate at least one schema (anyOf)       
- definitions.GqlSDLDefinitions.properties.inputObjectTypeExtensions.additionalProperties.items.originalRef in body is a forbidden property

validating spec APIGatewayUserManagementSwagger.json
The swagger spec at "APIGatewayUserManagementSwagger.json" is invalid 
against swagger specification 2.0. see errors :
- "authorizeUser" is defined 2 times

tomcruise81 commented 3 years ago

Additional validation issues with:

APIGatewayArchive.json
APIGatewayAdministration.json
APIGatewayAvailability.json

vpraveenon commented 3 years ago

@tomcruise81 - We will take a look and update

vpraveenon commented 2 years ago

Just to keep you updated, the issue is being worked upon

vpraveenon commented 2 years ago

@tomcruise81 - A fix has been provided. Can you check and update?

tomcruise81 commented 2 years ago

I'm still getting validation errors on those same spec files. However, the validation errors are now different. For example, for https://github.com/SoftwareAG/webmethods-api-gateway/blob/master/apigatewayservices/APIGatewayServiceManagement.json, I now get the following output:

validating spec APIGatewayServiceManagement.json
The swagger spec at "APIGatewayServiceManagement.json" is invalid against swagger specification 2.0. see errors :
- definition "GraphQLAPI" contains duplicate properties: [GraphQLAPI.serviceRegistryDisplayName GraphQLAPI.tags GraphQLAPI.apiTags]
- definition "RestAPI" contains duplicate properties: [RestAPI.serviceRegistryDisplayName RestAPI.apiTags RestAPI.tags]
- definition "GqlStringValue" contains duplicate properties: [GqlStringValue.comments]
- definition "BooleanSchema" contains duplicate properties: [BooleanSchema.type]
- definition "ODataAPI" contains duplicate properties: [ODataAPI.serviceRegistryDisplayName]
- definition "HeaderParameter" contains duplicate properties: [HeaderParameter.allowEmptyValue HeaderParameter.deprecated HeaderParameter.get$ref HeaderParameter.in HeaderParameter.name HeaderParameter._enum HeaderParameter.description HeaderParameter.xpath HeaderParameter.style HeaderParameter.allowReserved HeaderParameter.content HeaderParameter.default HeaderParameter.examples HeaderParameter.explode HeaderParameter.extendedExample HeaderParameter.parameterSchema HeaderParameter.required]
- definition "RefParameter" contains duplicate properties: [RefParameter.parameterSchema RefParameter.style RefParameter.default RefParameter.extendedExample RefParameter.name RefParameter.xpath RefParameter.allowEmptyValue RefParameter.content RefParameter.get$ref RefParameter.in RefParameter.required RefParameter.description RefParameter.examples RefParameter.explode RefParameter._enum RefParameter.allowReserved RefParameter.deprecated]
- definition "GqlNullValue" contains duplicate properties: [GqlNullValue.comments]
- definition "ObjectSchema" contains duplicate properties: [ObjectSchema.type]
- definition "GqlIntValue" contains duplicate properties: [GqlIntValue.comments]
- definition "GqlObjectValue" contains duplicate properties: [GqlObjectValue.comments]
- definition "GqlFloatValue" contains duplicate properties: [GqlFloatValue.comments]
- definition "GqlNonNullType" contains duplicate properties: [GqlNonNullType.comments]
- definition "GqlTypeName" contains duplicate properties: [GqlTypeName.comments]
- definition "StringSchema" contains duplicate properties: [StringSchema.default StringSchema.enum StringSchema.type]
- definition "GatewaySchema" contains duplicate properties: [GatewaySchema.type]
- definition "GqlVariableReference" contains duplicate properties: [GqlVariableReference.comments]
- definition "IntegerSchema" contains duplicate properties: [IntegerSchema.enum IntegerSchema.format IntegerSchema.type IntegerSchema.default]
- definition "BodyParameter" contains duplicate properties: [BodyParameter.allowEmptyValue BodyParameter.description BodyParameter.examples BodyParameter.get$ref BodyParameter.in BodyParameter.name BodyParameter.required]
- definition "GqlBooleanValue" contains duplicate properties: [GqlBooleanValue.comments]
- definition "QueryParameter" contains duplicate properties: [QueryParameter.examples QueryParameter.extendedExample QueryParameter.parameterSchema QueryParameter.style QueryParameter._enum QueryParameter.default QueryParameter.description QueryParameter.get$ref QueryParameter.allowEmptyValue QueryParameter.content QueryParameter.deprecated QueryParameter.name QueryParameter.xpath QueryParameter.allowReserved QueryParameter.explode QueryParameter.in QueryParameter.required]  
- definition "ArraySchema" contains duplicate properties: [ArraySchema.type]
- definition "GqlArrayValue" contains duplicate properties: [GqlArrayValue.comments]
- definition "SOAPAPI" contains duplicate properties: [SOAPAPI.serviceRegistryDisplayName SOAPAPI.tags SOAPAPI.apiTags]
- definition "FormParameter" contains duplicate properties: [FormParameter.default FormParameter.deprecated FormParameter.description FormParameter.examples FormParameter.get$ref FormParameter.style FormParameter._enum FormParameter.content FormParameter.name FormParameter.allowReserved FormParameter.in FormParameter.explode FormParameter.parameterSchema FormParameter.required FormParameter.xpath FormParameter.allowEmptyValue FormParameter.extendedExample]
- definition "NumberSchema" contains duplicate properties: [NumberSchema.default NumberSchema.enum NumberSchema.type]
- definition "GqlInterfaceTypeDefinition" contains duplicate properties: [GqlInterfaceTypeDefinition.comments GqlInterfaceTypeDefinition.directives GqlInterfaceTypeDefinition.name]
- definition "PathParameter" contains duplicate properties: [PathParameter.deprecated PathParameter.get$ref PathParameter.name PathParameter._enum PathParameter.allowEmptyValue PathParameter.content PathParameter.parameterSchema PathParameter.required PathParameter.default PathParameter.description PathParameter.explode PathParameter.xpath PathParameter.allowReserved PathParameter.examples PathParameter.in PathParameter.extendedExample PathParameter.style]
- definition "CookieParameter" contains duplicate properties: [CookieParameter.deprecated CookieParameter.parameterSchema CookieParameter.style CookieParameter.allowReserved CookieParameter.description CookieParameter.required CookieParameter.xpath CookieParameter._enum CookieParameter.allowEmptyValue CookieParameter.content CookieParameter.explode CookieParameter.extendedExample CookieParameter.get$ref CookieParameter.name CookieParameter.default CookieParameter.examples CookieParameter.in]
- definition "GqlEnumValue" contains duplicate properties: [GqlEnumValue.comments]
- definition "GqlListType" contains duplicate properties: [GqlListType.comments]
- definition "ModelImpl" contains duplicate properties: [ModelImpl.properties]
- operation "createAPI" has both formData and body parameters. Only one such In: type may be used for a given operation
- operation "updateAPI" has both formData and body parameters. Only one such In: type may be used for a given operation

Looking at the spec file for entries where it's indicated that there are "duplicate properties", I can see things like:

    "GraphQLAPI" : {
      "allOf" : [ {
        "$ref" : "#/definitions/API"
      }, {
        "type" : "object",
        "properties" : {
          "apiTags" : {
            "type" : "array",
            "description" : "A list of API level tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier",
            "items" : {
              "type" : "string"
            }
          },
          "nativeEndpoints" : {
            "type" : "array",
            "description" : "Native endpoints",
            "items" : {
              "$ref" : "#/definitions/NativeEndpoint"
            }
          },
          "sdlDefinitions" : {
            "$ref" : "#/definitions/GqlSDLDefinitions"
          },
          "serviceRegistryDisplayName" : {
            "type" : "string",
            "description" : "The name of the API in service registry when the API is published to a service registry."
          },
          "tags" : {
            "type" : "array",
            "description" : "A list of tags with additional metadata",
            "items" : {
              "$ref" : "#/definitions/Tag"
            }
          }
        }
      } ]
    }

But the "$ref": "#/definitions/API" reference also contains some of the same properties:

  "definitions" : {
    "API" : {
      "type" : "object",
      "discriminator" : "type",
      "properties" : {
        "apiTags" : {
          "type" : "array",
          "items" : {
            "type" : "string"
          }
        },
        "description" : {
          "type" : "string"
        },
        "serviceRegistryDisplayName" : {
          "type" : "string"
        },
        "tags" : {
          "type" : "array",
          "items" : {
            "$ref" : "#/definitions/Tag"
          }
        },
        "title" : {
          "type" : "string"
        },
        "type" : {
          "type" : "string"
        },
        "uri" : {
          "type" : "array",
          "uniqueItems" : true,
          "items" : {
            "type" : "string"
          }
        },
        "version" : {
          "type" : "string"
        }
      }
    },

which I'm guessing is why the validation is still complaining.

tomcruise81 commented 2 years ago

I'm using go-swagger. You can use their CLI to validate the spec files - https://github.com/go-swagger/go-swagger#validate-a-specification

necrolax commented 2 years ago

HI @tomcruise81 ,

Please check the swagger against https://editor.swagger.io/. We are validating the swagger against this endpoint only.

If you see this error Parameters cannot have both a "in: body" and "in: formData", as "formData" will be the body, we cannot fix this in swagger 2.0 as we are expecting both body and formData on the same endpoint.
For APIUserManagement the issue needs to be fixed. We are tracking that internally.
For all other warnings you can ignore.

tomcruise81 commented 2 years ago

If you're going against SmartBear's implementation, I can as well. I've used Swagger Codegen, which doesn't appear to be doing validation of the spec, and am still having a multitude of problems:

APIGatewayAvailability.json - "com.fasterxml.jackson.core.JsonParseException: Unexpected character ('}' (code 125)): was expecting double-quote to start field name..."

APIGatewayServiceManagement.json - a Golang client is produced, but the API spec is incorrect for the responses that are actually returned

Example - getAPIs:

"paths": {
"/apis": {
"get": {
    "description": "Get all APIs or subset of APIs",
    "operationId": "getAPIs",
    "produces": [
        "application/json"
    ],
    "parameters": [
        ...
    ],
    "responses": {
        "200": {
            "description": "Returns the list of all APIs",
            "examples": ...,
            "schema": {
                "type": "array",
                "items": {
                    "$ref": "#/definitions/APIResponseGetAPIs"
                }
            }
        },

    "APIResponseGetAPIs" : {
      "type" : "object",
      "properties" : {
        "active" : {
          "type" : "boolean"
        },
        "apiId" : {
          "type" : "string"
        },
        "apiName" : {
          "type" : "string",
          "description" : "API Name"
        },
        "apiVersion" : {
          "type" : "string",
          "description" : "API Version"
        },
        "errorReason" : {
          "type" : "string"
        },
        "id" : {
          "type" : "string",
          "description" : "API Id"
        },
        "publishedPortals" : {
          "type" : "array",
          "description" : "Published portals of an API",
          "items" : {
            "type" : "string"
          }
        },
        "responseStatus" : {
          "type" : "string",
          "enum" : [ "SUCCESS", "ERROR", "NOT_FOUND", "BAD_REQUEST", "PARTIAL_SUCCESS" ]
        },
        "systemVersion" : {
          "type" : "integer",
          "format" : "int32",
          "description" : "System version of an API"
        },
        "teams" : {
          "type" : "array",
          "description" : "Contains teams belonging to an API.",
          "items" : {
            "$ref" : "#/definitions/Team"
          }
        },
        "type" : {
          "type" : "string",
          "description" : "API Type"
        }
      },
      "description" : "This model contains the basics details of an API."
    },

Based on the spec, the response should be something like:

{
    "apiResponse": [
        {
            "apiName": ...,
            "apiVersion": ...,

However, the actual response for a call to this endpoint is something like (note the extra layer of nesting):

{
    "apiResponse": [
        {
            "api": {
                "apiName": ...,
                "apiVersion": ...,

That's as far as I've gotten while trying to utilize the spec files so there very well could be other inconsistencies between the spec and what the the APIs are actually doing.

tomcruise81 commented 2 years ago

Actually, based on the spec, the expectation is something more in line with (i.e. it's missing two layers of nesting):

[{
    "apiName": ...,
    "apiVersion": ...,

vpraveenon commented 2 years ago

@tomcruise81 - Can you please check the latest fix?

tomcruise81 commented 2 years ago

Sorry that it took me a bit. Still seeing a number of issues in the APIs that I've tested.

APIGatewayAdministration.json

getAllAPIPortalConfiguration - the spec is tied to a single element, whereas the REST API returns an array

APIGatewayPolicyManagement.json

Policy - object needs to wrap another level of object with a policy property, OR adjust how you reference the Policy object as a return type

APIGatewaySearch.json

SearchContext
- .scope - should be of type array, with "items" : { "$ref" : "#/definitions/SearchField" }
- .types - should be of type array, with "items" : { "type" : "string", "enum" : [ "USER", "GROUP", "USERS", "GROUPS", "ACCESSPROFILES", "LDAPGROUPS", "CDSGROUPS", "ASSERTION", "APPLICATION", "API", "ALIAS", "POLICY", "POLICY_ACTION", "PLAN", "PACKAGE", "ADMINISTRATOR_SETTING", "PORTAL_GATEWAY", "OAUTH2_SCOPE_DATA", "SUBSCRIPTION", "API_DOCUMENT", "APPROVAL_CONFIGURATION", "OUTBOUND_PROXY", "PROXY_BYPASS", "URL_ALIAS", "KEYSTORE", "TRUSTSTORE", "KERBEROS_SETTING", "JNDI_PROVIDER_ALIAS", "JMS_CONNECTION_ALIAS", "JMS_TRIGGER", "WEB_SERVICE_ENDPOINT_ALIAS", "ACCESS_CONTROL_LIST", "RULE", "MICROGATEWAY_GROUPS", "GATEWAY_SCOPE", "OAUTH2MATERIALIZEDTOKEN", "TRANSACTION_EVENTS", "LIFECYCLE_EVENTS", "POLICYVIOLATION_EVENTS", "MONITOR_EVENTS", "ERROR_EVENTS", "THREATPROTECTION_EVENTS", "PERFORMANCE_METRICS", "QUOTA_USAGE", "DASHBOARD", "AUDIT_LOG", "REQUEST_RESPONSE_TRACE_SPANS", "APPLICATION_LOG", "MEDIATOR_TRACE_SPANS", "SERVER_LOG_TRACE_SPANS" ] }

APIGatewayServiceManagement.json

APIResponse
- object needs to wrap another level of object with an apiResponse property, OR adjust how you reference the APIResponse object as a return type
- .versions array missing
APIResponseCreate
- object needs to wrap another level of object with an apiResponse property, OR adjust how you reference the APIResponseCreate object as a return type
APIResponseGetAPI
- object needs to wrap another level of object with an apiResponse property, OR adjust how you reference the APIResponseGetAPI object as a return type
- .gatewayEndPointsList array missing
APIResponseGetAPIs
- object needs to wrap another level of object with an apiResponse property, OR adjust how you reference the APIResponse object as a return type
- the apiResponse is an array of objects

Please note that this is in NOT intended to be a comprehensive list of the issues in the API specs, but rather just some of the issues that I've come across in my testing.

SoftwareAG / webmethods-api-gateway