Swagger does not support adding a summary and description to Path Item Objects. To provide this functionality, we will use the
x-description values as summary and description for these path item objects.
Swagger API Description using
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
The Swagger specification allows specifying examples only for request parameters
However, it is useful to know what values to use when testing an API, so
x-example vendor extension property to overcome the limitation:
... paths: /cars: get: parameters: - name: limit in: query type: number x-example: 42
x-example property is respected for all kinds of request parameters except
body parameters, where native
schema.example should be used.