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.
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.Last modified 5mo ago