Invalid swagger specification 2.0?

[tomcruise81]

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    

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

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]

Additional validation issues with:

• APIGatewayArchive.json
• APIGatewayAdministration.json
• APIGatewayAvailability.json

[vpraveenon]

@tomcruise81 - We will take a look and update

[vpraveenon]

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

[vpraveenon]

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

[tomcruise81]

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]

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]

HI @tomcruise81 ,

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

1. 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.
2. For APIUserManagement the issue needs to be fixed. We are tracking that internally.
3. For all other warnings you can ignore.

[tomcruise81]

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]

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]

@tomcruise81 - Can you please check the latest fix?