mirror of
https://github.com/Redocly/redoc.git
synced 2024-11-10 19:06:34 +03:00
Add vendor extensions docs
This commit is contained in:
parent
860eb30c48
commit
ad7629a640
|
@ -72,6 +72,13 @@ For npm:
|
|||
|
||||
## Configuration
|
||||
|
||||
#### Swagger vendor extensions
|
||||
ReDoc makes use of the following [vendor extensions](http://swagger.io/specification/#vendorExtensions):
|
||||
* [`x-logo`](docs/redoc-vendor-extensions.md#x-logo) - is used to specify API logo
|
||||
* [`x-traitTag`](docs/redoc-vendor-extensions.md#x-traitTag) - useful for handling out common things like Pagination, Rate-Limits, etc
|
||||
* [`x-code-samples`](docs/redoc-vendor-extensions.md#x-code-samples) - specify operation code samples
|
||||
|
||||
#### Options
|
||||
* `spec-url` - relative or absolute url to your spec file
|
||||
* `scroll-y-offset` - If set, specifies a vertical scroll-offset. This is often useful when there are fixed positioned elements at the top of the page, such as navbars, headers etc.
|
||||
`scroll-y-offset` can be specified in various ways:
|
||||
|
|
105
docs/redoc-vendor-extensions.md
Normal file
105
docs/redoc-vendor-extensions.md
Normal file
|
@ -0,0 +1,105 @@
|
|||
# ReDoc vendor extensions
|
||||
ReDoc makes use of the following [vendor extensions](http://swagger.io/specification/#vendorExtensions)
|
||||
|
||||
### <a name="infoObject"></a> [Info Object](http://swagger.io/specification/#infoObject) vendor extensions
|
||||
|
||||
#### <a name="x-logo"></a> x-logo
|
||||
| Field Name | Type | Description
|
||||
| :------------- | :------: |
|
||||
| x-logo | [Logo Object](#logoObject) | The information about API logo
|
||||
|
||||
##### Usage in Redoc
|
||||
`x-logo` is used to specify API logo. The corresponding image are displayed just above side-menu.
|
||||
|
||||
#### <a name="logoObject"></a> Logo Object
|
||||
The information about API logo
|
||||
##### Fixed fields
|
||||
| Field Name | Type | Description
|
||||
| :---------- | :------: |
|
||||
| url | string | The URL pointing to the spec logo. MUST be in the format of a URL
|
||||
| backgroundColor | string | background color to be used. MUST be in [CSS color syntax](https://developer.mozilla.org/en/docs/Web/CSS/color)
|
||||
|
||||
|
||||
##### x-logo example
|
||||
```yaml
|
||||
{
|
||||
"info": {
|
||||
"version": "1.0.0",
|
||||
"title": "Swagger Petstore",
|
||||
"x-logo": {
|
||||
"url": "https://rebilly.github.io/ReDoc/petstore-logo.png",
|
||||
"backgroundColor": "white"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
```yaml
|
||||
{
|
||||
info:
|
||||
version: "1.0.0"
|
||||
title: "Swagger Petstore"
|
||||
x-logo:
|
||||
url: "https://rebilly.github.io/ReDoc/petstore-logo.png"
|
||||
backgroundColor: "white"
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
### [Tag object](http://swagger.io/specification/#tagObject) vendor extensions
|
||||
|
||||
#### <a name="x-traitTag"></a> x-traitTag
|
||||
| Field Name | Type | Description
|
||||
| :------------- | :------: |
|
||||
| x-traitTag | boolean | In Swagger two operations can have multiply tags. This property distinguish between tags that are used to group operations (default) from tags that are used to mark operation with certain trait (`true` value)
|
||||
|
||||
##### Usage in Redoc
|
||||
Tags that have `x-traitTag` set to `true` are listed in side-menu but don't have any subitems (operations). Tag `description` is rendered as well.
|
||||
This is useful for handling out common things like Pagination, Rate-Limits, etc.
|
||||
|
||||
##### x-traitTag example
|
||||
```json
|
||||
{
|
||||
"name": "Pagination",
|
||||
"description": "Pagination description (can use markdown syntax)",
|
||||
"x-traitTag": true
|
||||
}
|
||||
```
|
||||
```yaml
|
||||
name: Pagination
|
||||
description: Pagination description (can use markdown syntax)
|
||||
x-traitTag: true
|
||||
```
|
||||
|
||||
### [Operation Object](http://swagger.io/specification/#operationObject) vendor extensions
|
||||
|
||||
#### <a name="x-code-samples"></a> x-code-samples
|
||||
| Field Name | Type | Description
|
||||
| :------------- | :------: |
|
||||
| x-code-samples | [[Code Sample Object](#codeSampleObject)] | A list of code samples associated with operation
|
||||
|
||||
##### Usage in ReDoc
|
||||
x-code-samples are rendered on the right panel of ReDoc
|
||||
|
||||
#### <a name="codeSampleObject"></a> Code Sample Object
|
||||
Operation code sample
|
||||
##### Fixed fields
|
||||
| Field Name | Type | Description
|
||||
| :---------- | :------: | :-----------
|
||||
| lang | string | Code sample language. Value should be one of the following [list](https://github.com/github/linguist/blob/master/lib/linguist/popular.yml)
|
||||
| source | string | Code sample source code
|
||||
|
||||
|
||||
##### Code Sample Object example
|
||||
```yaml
|
||||
{
|
||||
"lang": "JavaScript",
|
||||
"source": "console.log('Hello World');"
|
||||
}
|
||||
```
|
||||
```yaml
|
||||
{
|
||||
lang: JavaScript
|
||||
source: console.log('Hello World');
|
||||
}
|
||||
```
|
Loading…
Reference in New Issue
Block a user