Openapi-specification: Is it possible to include an external markdown document for a description?

[CameronGo]

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?

[darrelmiller]

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.

[CameronGo]

Thanks -

[kcavagnolo]

@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?

```yaml
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.
  ```

[RichardCullen]

Nice find, @kcavagnolo ! Just what I wanted!

[darrelmiller]

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

[renatga]

@darrelmiller

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