Is it possible to include an external markdown document for a description?

I'm trying to learn the OpenAPI specification and am coming from using RAML. I'm struggling a bit with best practices for organizing files and such to reduce clutter in my main OpenAPI/Swagger document. I'm trying to place a detailed description in the form of markdown and would like to keep it in a file outside the main, but I cannot for the life of me figure out how to go about doing this.

In RAML I would use an !include statement, but I haven't seen any mention of something like this in the examples. I've seen the $ref statements used, but not in exactly such a situation and no combination of using this in a description has worked for me so far.

Any help?

There is no mechanism for externalizing descriptions in OpenAPI. There would need to be some external tooling that has a pre-processor step to enable this.

Thanks -

@darrelmiller

@darrelmiller: Found this issue in a search before posting a new feature request. I'm using ReDoc to render API documentation and a $ref in a description field is being honored. I'm assuming I've discovered a workaround and not an officially supported feature of OAS3.0, yes?

openapi: 3.0.0

servers:
  - url: https://api.server.io/my-api/
    description: Production server

info:
  title: My API
  version: 0.0.0
  description: 
    $ref: ../frontmatter/api-summary.md
  contact:
    name: ...
    email: ...
    url: https://...
  termsOfService: https://...
  license:
    name: Proprietary
    url: https://...

tags:
  - name: service-group1
    description:
      $ref: ../frontmatter/service-group1-description.md
    externalDocs:
      url: https://...
      description: Explore our endpoint1 tutorials for guidance.

@kcavagnolo

Nice find, @kcavagnolo ! Just what I wanted!

@kcavagnolo

@kcavagnolo Correct, that is an not an officially supported solution.

@darrelmiller

@darrelmiller

You don't know how much it helped ! Half of inetrent are looking for this feature :)

@Caldwell1988

Thanks for this question and the answer. We are currently facing the same problem/decision.

There is one question that remains now.
As far as I understand OAS 3.1 will support all JSON Schema keywords including their meanings. We are aiming for OAS 3.1 with our new API, but writing it in OAS 3.0 for now, as tooling for 3.1 is not broadly available. Will the suggested solution here be an officially supported solution in OAS 3.1?

@Caldwell1988: You will be interested in this response.

@darrelmiller

@darrelmiller: Found this issue in a search before posting a new feature request. I'm using ReDoc to render API documentation and a $ref in a description field is being honored. I'm assuming I've discovered a workaround and not an officially supported feature of OAS3.0, yes?

openapi: 3.0.0

servers:
  - url: https://api.server.io/my-api/
    description: Production server

info:
  title: My API
  version: 0.0.0
  description: 
    $ref: ../frontmatter/api-summary.md
  contact:
    name: ...
    email: ...
    url: https://...
  termsOfService: https://...
  license:
    name: Proprietary
    url: https://...

tags:
  - name: service-group1
    description:
      $ref: ../frontmatter/service-group1-description.md
    externalDocs:
      url: https://...
      description: Explore our endpoint1 tutorials for guidance.

Would be great if this could be fully supported. It works great using while using redoc to generating an HTML with a reference to the markdown file. However, since it is not officially supported, we get errors in other places in our build. IE: Even the official swagger editor will complete about the format.

Structural error at tags.0.description
should be string

Navigation Menu

Repository navigation

Is it possible to include an external markdown document for a description? #1402

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Is it possible to include an external markdown document for a description? #1402

Description

Activity

darrelmiller commented on Nov 8, 2017

CameronGo commented on Feb 6, 2018

kcavagnolo commented on Feb 28, 2019

RichardCullen commented on Feb 28, 2019

darrelmiller commented on Mar 1, 2019

renatga commented on Oct 10, 2019

yaSebastian commented on Apr 27, 2021

flsing commented on Jan 15, 2023

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions