Swagger vendor extensions

x-summary and x-description

Swagger does not support adding a summary and description to Path Item Objects. To provide this functionality, we will use the x-summary and x-description values as summary and description for these path item objects.

Swagger API Description using x-summary and x-description

swagger: '2.0'
info:
  title: Polls Swagger
  description: Polls is a simple API allowing consumers to view polls and vote in them.
  version: "8234aab51481d37a30757d925b7f4221a659427e"
host: polls.apiblueprint.org
schemes:
  - https
paths:
  /questions:
    x-summary: Questions Collection
    x-description: |
      You may create your own question adding a member to this collection. It takes a JSON
      object containing a question and a collection of answers in the
      form of choices.
    get:
      summary: List all questions
      responses:
        200:
          description: 'List'
          examples:
            application/json:
              - question: "Favourite programming language?"
                published_at: "2015-08-05T08:40:51.620Z"
                choices:
                  - choice: "Swift"
                    votes: 2048
                  - choice: "Python"
                    votes: 1024
                  - choice: "Objective-C"
                    votes: 512
                  - choice: "Ruby"
                    votes: 256

x-example

The Swagger specification allows specifying examples only for request parameters in body (schema.example).

However, it is useful to know what values to use when testing an API, so we support x-example vendor extension property to overcome the limitation:

...
paths:
  /cars:
    get:
      parameters:
        - name: limit
          in: query
          type: number
          x-example: 42

The x-example property is respected for all kinds of request parameters except of body parameters, where native schema.example should be used.

x-nullable

As it is not possible to declare null as an additional type to schemas in Swagger 2 this brings a limitation where you cannot define types which are nullable. In OAS3 this limitation is removed with the introduction of the nullable property which when set to true allows null to be a value alongside the original value(s) or type(s). This feature is backported to our Swagger 2 parser as a vendored extension x-nullable.

For example, to declare a schema for a type that may be a string or null:

type: string
x-nullable: true

x-nullable may also be used in conjunction with enumerations. In the below example the schema represents that the permitted values are either one of the strings north, east, south, west or null:

enum:
  - north
  - east
  - south
  - west
x-nullable: true