1

Is it possible to reference OpenAPI operation description from an external file?

Here is my sample code. I want to keep the description "This API is used to get user details" in a separate file and use it here like a variable or template or as a reference. Is there any way to do this?

 get:
  tags:
    - User
  summary: Get user details
  description:  This API is used to get user details
  operationId: updateUser
  parameters:
    - name: userid
      in: path
      description: The id that needs to be pulled
      required: true
      schema:
        type: string

enter image description here

Helen
  • 87,344
  • 17
  • 243
  • 314
jestges
  • 3,686
  • 24
  • 59
  • 95

1 Answers1

2

If you use Redocly CLI to bundle, then you can put it in a separate file like this:

 get:
  tags:
    - User
  summary: Get user details
  description: 
    $ref: ./updateUser-description.md
  operationId: updateUser
  parameters:
    - name: userid
      in: path
      description: The id that needs to be pulled
      required: true
      schema:
        type: string

Then, in a separate file named updateUser-description.md (note, you could change the name too):

This API is used to get user details

Then, when you run the bundle command it resolves the $ref and replaces the description with the contents in that corresponding Markdown file.

npx @redocly/cli bundle my-openapi.yaml
Domino
  • 361
  • 1
  • 2
  • 7
  • Hi Domino, thanks for your quick response. But I'm getting this error when I use $ref like above. "Expected type `string` but got `object`.Redocly OpenAPI" – jestges Nov 03 '22 at 03:46
  • @jestges if you see this error in an editor (e.g. VS Code or Swagger Editor), that's expected because `$ref` usage in `description` is not standard OpenAPI syntax, it's custom syntax that Redocly supports. – Helen Nov 03 '22 at 06:18
  • I have updated Domino response by adding a static description. Is it possible to have like this? Description 1 as a fixed text and other from a reference file? Please let me know if there is any way – jestges Nov 03 '22 at 16:07
  • @jestges no. That is invalid YAML and also an invalid proposal. However, there are different ways to accomplish that, it would involve writing some custom code. Here is what you proposed (for historical context): ```yaml description: | "Description 1 here and description 2 from below ref" $ref: ./updateUser-description.md ``` – Domino Nov 06 '22 at 13:09