Redocly/redoc
1
1
Fork 0
mirror of https://github.com/Redocly/redoc.git synced 2024-11-23 00:56:33 +03:00
Code Issues Packages Projects Releases Wiki Activity
06ef51c08c
redoc/docs/redoc-vendor-extensions.md
Roman Hotsiy 63ae2e8e94
feat: support x-summary for response objects 
fixes #500
2018-06-01 16:50:07 +03:00

8.4 KiB
Raw Blame History

ReDoc vendor extensions

ReDoc makes use of the following vendor extensions

Swagger Object vendor extensions

Extend OpenAPI root Swagger Object

x-servers

Backported from OpenAPI 3.0 servers. Currently doesn't support templates.

x-tagGroups

Field Name Type Description
x-tagGroups [ Tag Group Object ] A list of tag groups
Usage in Redoc

x-tagGroups is used to group tags in the side menu. If you are going to use x-tagGroups, please make sure you add all tags to a group, since a tag that is not in a group, will not be displayed at all!

Tag Group Object

Information about tags group

Fixed fields
Field Name Type Description
name string The group name
tags [ string ] List of tags to include in this group
x-tagGroups example

json

{
  "x-tagGroups": [
    {
      "name": "User Management",
      "tags": ["Users", "API keys", "Admin"]
    },
    {
      "name": "Statistics",
      "tags": ["Main Stats", "Secondary Stats"]
    }
  ]
}

yaml

x-tagGroups:
  - name: User Management
    tags:
      - Users
      - API keys
      - Admin
  - name: Statistics
    tags:
      - Main Stats
      - Secondary Stats

x-ignoredHeaderParameters

Field Name Type Description
x-ignoredHeaderParameters [ string ] A list of ignored headers
Usage in Redoc

x-ignoredHeaderParameters is used to specify header parameter names which are ignored by ReDoc

x-ignoredHeaderParameters example
swagger: '2.0'
info:
  ...
tags: [...]
x-ignoredHeaderParameters:
  - Accept
  - User-Agent
  - X-Test-Header

Info Object vendor extensions

Extends OpenAPI Info Object

Field Name Type Description
x-logo Logo Object 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.

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. It SHOULD be an absolute URL so your API definition is usable from any location
backgroundColor string background color to be used. MUST be RGB color in [hexadecimal format] (https://en.wikipedia.org/wiki/Web_colors#Hex_triplet)
x-logo example

json

{
  "info": {
    "version": "1.0.0",
    "title": "Swagger Petstore",
    "x-logo": {
      "url": "https://rebilly.github.io/ReDoc/petstore-logo.png",
      "backgroundColor": "#FFFFFF"
    }
  }
}

yaml

info:
  version: "1.0.0"
  title: "Swagger Petstore"
  x-logo:
    url: "https://rebilly.github.io/ReDoc/petstore-logo.png"
    backgroundColor: "#FFFFFF"

Tag Object vendor extensions

Extends OpenAPI Tag Object

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)

x-displayName

Field Name Type Description
x-displayName string Define the text that is used for this tag in the menu and in section headings
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 vendor extensions

Extends OpenAPI Operation Object

x-code-samples

Field Name Type Description
x-code-samples [ Code Sample Object ] A list of code samples associated with operation
Usage in ReDoc

x-code-samples are rendered on the right panel of ReDoc

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
source string Code sample source code
Code Sample Object example

json

{
  "lang": "JavaScript",
  "source": "console.log('Hello World');"
}

yaml

lang: JavaScript
source: console.log('Hello World');

Parameter Object vendor extensions

Extends OpenAPI Parameter Object

x-examples

Field Name Type Description
x-examples Example Object Object that contains examples for the request. Applies when in is body and mime-type is application/json
Usage in ReDoc

x-examples are rendered in the JSON tab on the right panel of ReDoc.

Response Object vendor extensions

Extneds OpeanAPI Response Object

x-summary

Field Name Type Description
x-summary string a short summary of the response
Usage in ReDoc

If specified, x-summary is used as the response button text. Description is rendered under the button.

Schema Object vendor extensions

Extends OpenAPI Schema Object

x-nullable

Field Name Type Description
x-nullable boolean marks schema as a nullable
Usage in ReDoc

Schemas marked as x-nullable are marked in ReDoc with the label Nullable

x-extendedDiscriminator

ATTENTION: This is ReDoc-specific vendor extension. It won't be supported by other tools.

Field Name Type Description
x-extendedDiscriminator string specifies extended discriminator
Usage in ReDoc

ReDoc uses this vendor extension to solve name-clash issues with the standard discriminator. Value of this field specifies the field which will be used as a extended discriminator. ReDoc displays definition with selectpicker using which user can select value of the x-extendedDiscriminator-marked field. ReDoc displays the definition which is derived from the current (using allOf) and has enum with only one value which is the same as the selected value of the field specified as x-extendedDiscriminator.

x-extendedDiscriminator example

Payment:
  x-extendedDiscriminator: type
  type: object
  required:
    - type
  properties:
    type:
      type: string
    name:
      type: string

CashPayment:
  allOf:
    - $ref: "#/definitions/Payment"
    - properties:
        type:
          type: string
          enum:
            - cash
        currency:
          type: string

PayPalPayment:
  allOf:
    - $ref: "#/definitions/Payment"
    - properties:
        type:
          type: string
          enum:
            - paypal
        userEmail:
          type: string

In the example above the names of definitions (PayPalPayment) are named differently than names in the payload (paypal) which is not supported by default discriminator.