yamlswaggeropenapiredocly

How to reference OpenAPI operation description from an external file?

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

Solution

  • 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