Skip to content

Proposal: Having an example for an entire operation in one place (request + response) #859

Open
@amarzavery

Description

@amarzavery

The current mechanism to provide examples for artifacts in a swagger spec is fragmented. It does not give the consumer an overview (or a bird's eye view) of an example to complete that operation successfully.

If the example object is opened up and can be provided per operation then this solves the problem. People can provide multiple examples (variations) for that operation. It can be very easily used for documenting and (live/mock) testing the API.

Please read the detailed proposal over here. Currently we have implemented an extension named "x-ms-examples" for our specs. The schema for this extension can be found here.

It would be nice to see what the community thinks about it and if it is possible to get this approach formally in the open api specification.

Metadata

Metadata

Assignees

No one assigned

    Labels

    example obj/keywordsIssues with the Example Object or exampel(s) keywords

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions