Enum in path generates invalid Swagger schema

[seantempleton]

Validating the schema generated from the following controller gives a Swagger schema parsing error.

public class AnimalController : ApiController
{
    public enum Animal { Fox }

    [HttpGet]
    [Route("Animal/{animalId}")]
    public IHttpActionResult GetAnimal(Animal animalId)
    {
        return Ok();
    }
}

The generated YAML is

x-generator: NSwag v11.3.3.0 (NJsonSchema v9.4.3.0)
swagger: '2.0'
info:
  title: Web API Swagger specification
  version: 1.0.0
schemes: []
consumes:
  - application/json
produces:
  - application/json
paths:
  '/Animal/{animalId}':
    get:
      tags:
        - AnimalControllerr
      operationId: AnimalController_GetAnimal
      parameters:
        - type: integer
          name: animalId
          in: path
          required: true
          schema:
            $ref: '#/definitions/Animal'
          x-nullable: false
      responses:
        '200':
          description: ''
          schema:
            type: file
          x-nullable: true
definitions:
  Animal:
    type: integer
    description: ''
    x-enumNames:
      - Fox
    enum:
      - 0
parameters: {}
responses: {}
securityDefinitions: {}

Running this through the Swagger Editor generates the following error:

Schema error at paths./Animal/{animalId}.get.parameters[0]
is not exactly one from <#/definitions/parameter>,<#/definitions/jsonReference>

According to the Swagger documentation (in the FAQ at the bottom), "schema is only used with in: body parameters".
Removing the schema: field from the parameter then validates properly with the Swagger Editor.

I am attempting to use swagger-diff to ensure my API is backwards compatible at all times, but it too throws an error because of the schema: field.

[RicoSuter]

The problem is that the schema reference to the enum is needed to generate correct code. Without this essential information is missing. Why is it even evaluated when it is not allowed? Is there any way to fix this without removing the field?

[RicoSuter]

Ref: #328

[seantempleton]

Thanks for the quick reply Rico. I'm sorry, I searched for existing issues but I didn't find #328.

I'm sure the validators are just iterating over the whole structure and ensuring that all the rules for a valid schema are met.

I can really only think of three options.

1. Give NSwag an option that says force compliance to the specification. i.e. don't output the schema reference, or do anything else which would make it not conform to the specification. I would prefer that over an option for simply not outputting the schema reference since that is very specific.
2. Have the validators not check for the schema reference. (Highly unlikely since that is their purpose in the first place, to ensure that a document fully conforms to the specification. Plus, there are a lot of validation programs and websites.)
3. For my use only, generate the document with NSwag, then write a custom script to remove the schema reference.

In my use case, neither I or anyone else will be generating code from the documentation created. It will simply be analyzed and compared with a previous version of the document to ensure that there were no breaking changes.
For that reason I would of course prefer option 1, but I can certainly do option 3 if needed.

[RicoSuter]

The 4th option: In this special case (enum parameter) generate an x-schema field and use this in NSwag as fallback when generating code and no schema field is set...

However i hoped that there is a way to correctly describe a primitive parh/query enum parameter. But it seems that this is not possible...

[RicoSuter]

We are now using x-schema to generate a valid specand additionally inline the enum for tools which do not support x-schema...