Redocly enables you to embed external Markdown file contents into description fields by passing an object to a description with a $ref JSON reference.
Sample excerpt of a OpenAPI YAML file:
openapi: '3.0.0'
info:
version: 1.0.0
title: My example API
description:
$ref: /path/to/file.md
To learn more about Markdown, visit: https://spec.commonmark.org/0.29/
There are three special HTML tags supported in the Markdown description.
Use the “SecurityDefinitions” tag to insert the section about authentication described within the security definitions of your OpenAPI definition.
# Authentication We love security! <SecurityDefinitions />
Use the “PullRight” tag to pull content into the right-most panel.
# Tutorial (displayed in the left navigation) <PullRight> This part will appear in the right pane. </PullRight> This part is in the body. Lorem ipsum dolor!
Use the “RedocResponse” tag to insert a section about a response. This is useful for describing errors where you want to link to the documentation directly to a specific error response. It can help you adopt or support problem+json: https://tools.ietf.org/html/rfc7807
# Errors
We follow the error response format proposed in [RFC 7807](https://tools.ietf.org/html/rfc7807)
also known as Problem Details for HTTP APIs. As with our normal API responses,
your client must be prepared to gracefully handle additional members of the response.
## Unauthorized
<RedocResponse pointer={"#/components/responses/Unauthorized"} />
## AccessForbidden
<RedocResponse pointer={"#/components/responses/AccessForbidden"} />
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4