Swagger can be extended with 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.

Was this page useful?
Thank you for the feedback!
What went wrong?