Bump
Search…
Markdown support
Use of markdown helps create comprehensive and structured API documentation.
Bump supports common Markdown syntax, language color syntax highlighting, and information call-outs. Markdown can be included inside your contract file or as an external reference using dedicated Markdown files. Here's several options that may help.
Common Markdown syntax support
Formatting
Markdown syntax
Rendering
bold
**bold**bold
italic
_italic_italic
inline code
̀ inline code ̀inline codestrike-through
~~strikethrough~~strikethrough
footnote
Footnote[^1]Footnote¹
¹: Content of the first footnote
quotes
> quotes- quotes
Titles & headings
- Heading 1:
# A first-level title - Heading 2:
## A second-level title - Heading 3:
### A third-level title
Multi-line code blocks with language color syntax highlighting
E.g.
1
```json
2
{
3
"hello": "world",
4
"number": 1,
5
"boolean": true
6
}
7
```
Copied!
will render:
1
{
2
"hello": "world",
3
"number": 1,
4
"boolean": true
5
}
Copied!
Information call-outs
Bump support information call-outs (of type
info, warn, success or error) with the quote markdown syntax (lines starting with > ) if the first line contains one of the call-out types.E.g.
1
> info
2
> this is an important information to **standout**
Copied!
will render:
this is an important information to standout
Markdown files as an external reference
Markdown files can be included as an external reference within your contract document with the $ref syntax
$ref: "./path/to/local-markdown.md". In the same way you can extract part of your contract (usually JSON schema of your models into dedicated *.yaml or *.json files), you can extract your markdown content into dedicated files too.E.g. Your OpenAPI contract
api-contract.yml can thus looks like:1
openapi: 3.1.0
2
info:
3
title: Bump API documentation
4
version: 1.0.0
5
description:
6
$ref: "./docs/introduction.md"
7
x-topics:
8
- title: Getting started
9
content:
10
$ref: "./docs/getting-started.md"
11
- title: Use cases
12
content:
13
$ref: "./docs/use-cases.md"
14
example:
15
$ref: "./docs/use-cases-examples.md"
16
servers:
17
...
18
paths:
19
...
Copied!
With files
docs/introduction.md, docs/getting-started.md, docs/use-cases.md and docs/use-cases-examples.md right next to your contract document, you will be able to generate a comprehensive API documentation with nicely formatted content for your users.It's a great way to include “Topic” sections with handwritten content before the documentation of endpoints/webhooks (or channels in case of an AsyncAPI contract) in dedicated Markdown files. Thanks to the
x-topics top-level property in your contract as explained in the dedicated help page.Adding topics to your documentation
Creating good API documentation requires giving users context and guides. As most of the specifications don't permit to add generic content, we have created a custom property. Setting the
x-topics property at the root of your documentation specification will let you add some content sections at the beginning of your documentation.Each topic can have the following properties:
Property
Description
title
Topic title as it will appear in the navigation bar and in the content section.
content
The topic content. Markdown is fully supported here.
example
Will appear in the examples section, if activated. Markdown is fully supported here.
Example:
1
x-topics:
2
- title: Getting started
3
content: Before using the API you need to get an API key by sending us an email.
4
- title: Authentication
5
content: Send the `X-API-KEY` header with all your requests.
6
example: |
7
```
8
$ curl \
9
-X POST https://api.example.com/endpoint/ \
10
-H "X-API-KEY: XXXXXX" \
11
```
Copied!
Last modified 27d ago