Writing contentComponents

Endpoint Response Snippet

The EndpointResponseSnippet component is used to reference an endpoint response from your API Reference. Below is an example of referencing the response for the POST /chat/{domain} endpoint.

Markdown
1<EndpointResponseSnippet endpoint='POST /chat/{domain}' />

will be rendered as

Response
1{
2  "turns": [
3    {
4      "role": "user",
5      "content": "string"
6    }
7  ],
8  "citations": [
9    "string"
10  ]
11}

Reference particular examples

If you want to reference a particular example in the response snippet, you can set example prop to the name of the example. See the steps below:

1

Define named examples

The highlighted lines show how to set the example name.

openapi.yml
1paths:
2  /pet/{petId}:
3    put:
4      summary: Get a pet 
5      operationId: pets_get
6      responses: 
7        '200': 
8          content:
9            application/json:
10              schema:
11                $ref: '#/components/schemas/Pet'
12              examples:
13                ExampleWithMarkley:
14                  summary: This is an example of a Pet
15                  value: 
16                    name: Markley
17                    id: 44
pets.yml
1service:
2  auth: true
3  base-path: ""
4  endpoints:
5    update:
6      docs: Get a pet
7      method: GET
8      path: /pet/{petId}
9      response: Pet
10      examples:
11        - name: ExampleWithMarkley
12          docs: This is an example of a Pet
13          response:
14            body: 
15              name: Markley
16              id: 44
2

Reference the example

In the API Definition, the example had a name ExampleWithMarkley. You can reference the example directly:

Markdown
1  <EndpointResponseSnippet 
2    endpoint="GET /pet/{petId}" 
3    example="ExampleWithMarkley"
4  />