Type and format are missing on some parameters in my swagger output

[jeff-r-koyaltech]

I am getting a JSON schema error on the first parameter (but not the second one) when I look at it using the live demo on http://editor.swagger.io

"parameters": [
{
"name": "scopeType",
"in": "query",
"required": true,
"x-nullable": false,
"$ref": "#/definitions/WsScopeType"
},
{
"type": "integer",
"name": "scopeId",
"in": "query",
"required": true,
"x-nullable": false,
"format": "long"
}
],

I want to collect more information for you to troubleshoot this error, but I'm not familiar enough yet with your code base. Do you have any suggestions on what to try / look at?

I think the C# type it's choking on may be an enum.

[jeff-r-koyaltech]

Generated via MSBuild
$(NSwagExe) webapi2swagger /assembly:$(OutDir)/$(AssemblyName).dll /output:Documentation$(AssemblyName).Swagger.json

[RicoSuter]

What error?

[jeff-r-koyaltech]

Swagger Error
Not a valid parameter definition
Jump to line 1397
Details
Object
code: "ONE_OF_MISSING"
params: Array [0]
message: "Not a valid parameter definition"
path: Array [5]
0: "paths"
1: "/api/Tenant/SetScope"
2: "post"
3: "parameters"
4: "0"
schemaId: "http://swagger.io/v2/schema.json#"
inner: Array [2]
0: Object
code: "ONE_OF_MISSING"
params: Array [0]
message: "Data does not match any schemas from 'oneOf'"
path: Array [5]
inner: Array [2]
1: Object
code: "OBJECT_MISSING_REQUIRED_PROPERTY"
params: Array [1]
message: "Missing required property: $ref"
path: Array [5]
level: 900
type: "Swagger Error"
description: "Not a valid parameter definition"
lineNumber: 1397

[RicoSuter]

Can you post the full swagger spec?

[RicoSuter]

I think the $ref is not allowed here...

[RicoSuter]

Ok, the problem is that the parameter type "Query" only allows primitive types, and enum is considered primitive... the problem is that refs are not allowed together with other properties:

OAI/OpenAPI-Specification#300

However it seems that in the next version, the "schema" property is also allowed for other parameter types and we can reference the enum this way:

OAI/OpenAPI-Specification#654

However this is/may not be compatible with Swagger 2.0 and the editors... but for now I'll change to that because its more valid then the current output...

[RicoSuter]

The problem is here:

[RicoSuter]

Added this fix/hack: 66336a3

As you can see there is no simple solution. There are two options:

• Be Swagger 2.0 compliant: But then enums have to be redefined (because they cannot be referenced) and a matching algorithm is needed so that enums are not generated twice (when generating client code)
• Use Swagger vNext for this (be non-compliant): Use "schema" attribute (as in the latest commit). This behavior can be implemented by other clients without breaking compatibility with older specs

Please clone the latest commit from "master" and try yourself, maybe its fine now?

The parameter should now look like:

[{
    "name": "scopeType",
    "in": "query",
    "required": true,
    "x-nullable": false,
    "schema": {
        "$ref": "#/definitions/WsScopeType"
    }
},
{
    "type": "integer",
    "name": "scopeId",
    "in": "query",
    "required": true,
    "x-nullable": false,
    "format": "long"
}]

[jeff-r-koyaltech]

I was able to check your solution this morning. It looks like it's sticking both in there now:
"parameters": [
{
"name": "scopeType",
"in": "query",
"required": true,
"schema": {
"$ref": "#/definitions/WsScopeType"
},
"x-nullable": false,
"$ref": "#/definitions/WsScopeType"
},
{
"type": "integer",
"name": "scopeId",
"in": "query",
"required": true,
"x-nullable": false,
"format": "long"
}
],

[RicoSuter]

With the latest commits, a parameter should look like (for a nullable Gender?):

    "parameters": [
      {
        "type": "string", 
        "name": "gender",
        "in": "query",
        "required": true,
        "schema": {
          "$ref": "#/definitions/Gender"
        },
        "x-nullable": true
      }
    ],

The "type" is declared twice (in the parameter and "schema" reference) so that generators which do not support "schema" and non-body parameters use this "type" as fallback.

[RicoSuter]

Is this ok? (this is a compromise we have to do with the Swagger 2.0 specification).

[jeff-r-koyaltech]

I understand the need to compromise. This helps me out a lot. Thanks for making the change!