Openapi-specification: Re-usable enums in path/query parameters

[marcus-maws]

I've been told that it's not possible to use schemas in path/query parameters, but I have a case where multiple paths use the same enum pattern for inputs.

For example, I have the following pattern that is duplicated over many paths:

parameters:
- in: "query"
  ...
  enum: 
  - id
  - sku
  - guid
  - stock
  ...

Is it possible to generalize this in some way, so that I don't have to define them for each path, but can just reference them?

[webron]

I think we've had a similar issue about it, or someone was talking about it in the mailing list. I think it's a fair request to avoid repetitions for 'primitive' definitions as well and it's something we should look into in the next version of the spec.

[marcus-maws]

OK, thanks for the quick response.

[webron]

No, don't close it :) It's good to get feedback from others as well.

[marcus-maws]

OK. :-)

[marcus-maws]

On a separate issue (touched on in https://github.com/swagger-api/swagger-spec/issues/290), I have a situation where multiple paths can take the same collection of parameters. It appears that again, I have to define all those parameters individually for each path. Being able to separate all those parameters would be useful as well.

[webron]

That should be a separate issue though. However, you can define parameters in a single place and then refer to them from multiple paths.

[mohsen1]

If you're writing you specs in YAML you can take advantage of YAML anchors to avoid reputations.

[webron]

But since there's a solution for that in the spec, it's better to utilize than than to utilize a solution that's can't be converted back and forth between JSON and YAML.

[webron]

My bad, I thought @mohsen1 referred to repeating the parameters. His solution is most certainly valid for the original request though!

[JamesMessinger]

This is already doable, though perhaps not very intuitive:
https://github.com/BigstickCarpet/swagger-parser/blob/master/tests/files/non-object-refs.yaml#L40

[Ckim15]

@mohsen1, Could you provide a working sample yaml spec where I can avoid repetition for enum?

I checked BigStickCarpet's url (https://github.com/BigstickCarpet/swagger-parser/blob/master/tests/files/non-object-refs.yaml#L40), It doesn't work.

[mohsen1]

@chanthakim15 Here is a quick example

---
swagger: '2.0'
info:
  version: 1.0.0
  title: Pets Store
paths:
  /pets:
    get:
      responses:
        200:
          description: Returns all the pets
          schema:
            $ref: '#/definitions/List'
        201:
          description: Returns all the pets
          schema:
            $ref: '#/definitions/Set'

definitions:
  List:
    type: string
    enum: &my-list
      - one
      - two
      - three
  Set:
    type: string
    enum: *my-list

@BigstickCarpet's example is correct. If any of swagger tools is not supporting it, it's a bug. Please file a bug for it.

[rdrey]

I just asked about it here: http://stackoverflow.com/questions/32255384/swagger-reusing-an-enum-definition-as-query-parameter

So :+1: , thanks

[webron]

OMG, what a coincidence, I just answered on it there too! :wink:

[rdrey]

:P Thanks! Got the YAML reference trick to work, only issue I had is that the order in the file seems to be important. (Sorry, I'm a YAML noob.) So now I have definitions above paths.

[webron]

Actually, the order is meaningless.

[rdrey]

Unidentified alias "OperationType" at line 78, column 33: enum: *OperationType ^

Flip the order, all good

EDIT: Some more info: Using a local copy of the Swagger Editor. Did reproduce with http://editor.swagger.io/#/ as well, quickly

[webron]

That sounds like a parsing bug.

[rdrey]

Would you like a minimal example to repro in here? Or should I open a new issue?

[webron]

It's got nothing to do with swagger-spec. I'm not sure which project is giving you the error, but if you want to report it, you should report it on the right one.

[rdrey]

Makes sense, sorry. Will report to Swagger Editor, but not sure which parser they use internally.

[webron]

Doesn't matter. @mohsen1 definitely knows more about it than me, so I could be mistaken, but better keep that information in swagger-editor. Thanks!

[gersongoulart]

+1 for this feature baked in Swagger. I think the "YAML reference" serves as good inspiration to how the Swagger schema could handle this... e.g.:

// (...)
"parameters": {
    "marketIds": {
        "name": "marketIds",
        "$ref": "#/definitions/idsParam"
    },
    "clientIds": {
        "name": "clientIds",
        "$ref": "#/definitions/idsParam"
    },
},
// (...)
"definitions": {
    "idsParam": {
        "in": "query",
        "required": false,
        "description": "One or more id integers as a comma delimited array",
        "type": "array",
        "items": {
              "type": "integer"
        }
},

[fehguy]

Unfortunately $ref cannot have a peer in the json model, per JSON schema.

[webron]

This is also covered by #301.

Parent issue: #565.

[webron]

Resolved with #654.

[scara]

Will report to Swagger Editor, but not sure which parser they use internally.

For those still interested: https://github.com/swagger-api/swagger-editor/issues/609#issuecomment-135530861.

HTH,
Matteo