openapi: 3.0.2
info:
title: Links
version: "1.0"
description: |
# Various ways to create links in RapiDoc
- Use markdown syntax to create
- Internal links to various sections of the document
- External links to other websites
- Convert headings to links on the Navigation bar
- Use custom HTMLs and styling to create buttons, links etc
## Markdown syntax to create links
## Internal Links
RapiDoc assigns auto generated IDs to important sections of the document.
You may use these IDs in your markdown syntax to create clickable links to varous sections of the document
below is how RapiDoc will assign IDs to different section
| Section | ID | Note |
| ----------------| ----------------- | ----- |
| Overview | `overview` | |
| API Servers | `servers` | |
| Authentications | `auth` | |
| Tags | `tag--{tag-name}` | `#` `:` `?` `&` `=` `{` `}` and `space` is replaced by hyphen (`-`) |
| Paths/Operations| `{method}-{path}` | `#` `:` `?` `&` `=` `{` `}` and `space` is replaced by hyphen (`-`) |
**Example:** ID of the operation `POST /users/find-by-name/{name}` is `post-/users/find-by-name/-name-` _(**Note:** that curlies around the name is replaced by hyphens)_
**Use Markdown syntax**
Now that you understand how the IDs are generated, you may use Markdown syntax to create links to various sections
```
[My Link Text](#link-id)
```
below are some of the links to various sections
- [Take me to API server ](#servers)
- [Operation: Get Single User ](#get-/users/-userId-)
## External Links
Just Like internal links you can use markdown syntax to create external links
```
[Take me to RapiDoc Homepage ](https://mrin9.github.io/RapiDoc/)
```
[Take me to RapiDoc Homepage ](https://mrin9.github.io/RapiDoc/)
## HTML Links
RapiDoc allows you to embed custom HTMLs in various slots.
| Slot | Location |
| ----------------| -------------------- |
|`(default)` | top of the document |
|`header` | on header bar |
|`footer` | bottom of document |
|`logo` | top-left of header |
|`nav-logo` | top of side navigation bar |
below is how you can embed custome HTML content. Unlike markdown links HTML links can be styled by the user, like providing a diffrent color, font etc
```html
...
Get User Operation
RapiDoc Home
```
As an example you can checkout this document's top-right corner, where you will find custom styled **HTML Links**
## Headings as navigation links
You can turn **level-1 and level-2 headings to links** on Navigation bar using `info-description-headings-in-navbar='true'` option
```html
...
```
As an example you can checkout this document's Navigation Bar, where you will find links to level-1 and level-2 heading
servers:
- url: https://reqres.in/api/
paths:
/users:
get:
description: List of users (paginated)
parameters:
- name: page
in: query
schema:
type: integer
example: 2
- name: delay
in: query
description: for simulating response delay. Do not provide any value for page parameter(0 indicates no delay)
examples:
- '0'
- 3
schema:
type: integer
minimum: 0
maximum: 10
responses:
'200':
description: Successful operation
content:
application/json:
schema:
type: object
description: Description of **User** object
properties:
page:
description: Current Page number
type: integer
per_page:
description: Number of records per page
type: integer
total:
description: Total number of records
type: integer
total_pages:
type: integer
data:
type: array
description: List of users
items:
$ref: '#/components/schemas/user'
support:
$ref: '#/components/schemas/support'
post:
description: Create a user
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/userInput"
responses:
201:
description: User creation response
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/userInput'
- $ref: '#/components/schemas/createUserResponse'
/users/{userId}:
get:
description: Get a Single User
parameters:
- in: path
name: userId
schema:
type: integer
example: 3
required: true
description: Numeric ID of the user to get
responses:
200:
description: Response when a user is found
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/user'
support:
$ref: '#/components/schemas/support'
404:
description: User Not found
components:
schemas:
user:
type: object
properties:
id:
description: User ID
type: integer
email:
description: User Email
type: string
first_name:
description: First Name
type: string
last_name:
description: Last Name
type: string
avatar:
description: Avatar URL
type: string
support:
type: object
properties:
url:
description: Support URL
type: string
text:
description: Support URL - Description
type: string
userInput:
type: object
properties:
name:
description: User Name
type: string
job:
description: Job
type: string
createUserResponse:
type: object
properties:
id:
type: integer
createdAt:
type: string