how to set one value for few key's in YAML object

Question

As far as I know there is no way to attach few keys to the single value in {key : value} pair in YAML. I am new to Swagger documentation (OpenAPI 3.0) and wondering is it possible somehow to combine my values together. For instance, I am messing with REST API documentation and when I want to list few responses without rewriting it every time, I have the following :

paths:
  /users:
      post:
//some additional information here
        responses:
          '500':
//and for example here I want to add not only 201 status code but also others
                description: >-
                  Something went wrong on back end
//however I have to do something like this (writing them all)
          '502':
                description: >-
                  Something went wrong on back end
//and so on..

What is best practices to overcome that? Maybe I have a bad point from the beginning.

1

YAML comments start with `#`. – flyx Dec 18 '18 at 15:37

score 3 · Accepted Answer · answered Dec 18 '18 at 15:40

3

You can use anchors and aliases:

path:
  /users:
    responses:
      '500':
        description: &desc1 >-
          Something went wrong on back end
      '502':
        description: *desc1

answered Dec 18 '18 at 15:40

flyx

35,506
7
89
126

YAML anchors may or may not work depending on the OpenAPI parser used. – Helen Dec 18 '18 at 17:10
2

@Helen well OpenAPI explicitly specifies that a document may be represented as YAML and applies no restrictions to anchor/alias usage, so if a parser does not support it, that is a bug in the parser. – flyx Dec 18 '18 at 17:49

Helen · Answer 2 · 2018-12-18T17:32:33.530

1

OpenAPI 3.0 supports response ranges '1XX'-'5XX' that can be used instead of listing the codes individually:

    responses:
      '5XX':
        description: Something went wrong on back end

If you still want to list the response codes individually but they have the same description and schema, you can $ref the common response definition like so:

    responses:
      '501':
        $ref: '#/components/schemas/BackendErrorResponse'
      '502':
        $ref: '#/components/schemas/BackendErrorResponse'

components:
  responses:
    BackendErrorResponse:
      description: Something went wrong on back end
      content:
        application/json:
          schema:
            ...

There's also an enhancement request in the OpenAPI Specification repository to allow reusing description across different responses.

edited Dec 18 '18 at 17:32

answered Dec 18 '18 at 17:22

Helen

87,344
17
243
314

Okay, I am very grateful for your help however there another question appeared. So, for example I have managed my problem with your second solution and now I have the following responses: `responses: BadRequest: description: Bad request content: application/json: schema: $ref: '#/components/schemas/error' Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/error'` Is it possible somehow to reuse similar content? – Omelian Levkovych Dec 18 '18 at 18:28
Sorry, I still do not know how to format code in comments well. – Omelian Levkovych Dec 18 '18 at 18:32
If you mean reusing the `content` key, OpenAPI does not support `$ref`'erencing the `content` key, you can `$ref` either the whole response (description + content) or just the content `schema`. But you can try YAML anchors [as suggested by flyx](https://stackoverflow.com/a/53836457/113116). YAML anchors should work in Swagger Editor and Swagger UI, but I don't know about other tools. – Helen Dec 18 '18 at 18:47

how to set one value for few key's in YAML object

2 Answers2