HTTP authoring guides

Describe a workshop route as one OpenAPI operation

·

The workshop agenda route needs a workshop identifier in its path and an optional preference for showing drafts. Model both and check that the exported operation describes how they differ.

REST API Endpoint Builder

Build the GET workshop agenda operation

Load the example. Its Path template is /workshops/{workshopId}/agenda. The first parameter line declares workshopId as a required integer in the path. The second declares an optional includeDrafts boolean in the query.

The response is status 200 with application/json and an object schema. Select Build OpenAPI. The result contains an info object and one get operation under the exact path template.

Parameters for the agenda route
path workshopId integer required
query includeDrafts boolean optional

OpenAPI 3.1.1 — Path templatingOpenAPI 3.1.1 — Operation object

Compare the parameter objects in openapi.json

Download the JSON and inspect the operation’s parameters array. workshopId has in set to path, required set to true, and a schema type of integer. includeDrafts has in set to query and required set to false.

Rename workshopId in its parameter line without changing the route placeholder. Building again identifies the mismatch. Keep the names identical, including case.

OpenAPI 3.1.1 — Parameter object

Document the body that a client should expect

Choose a different Response schema to describe the returned value, such as an array for a list of workshops. The result places the schema under the selected media type.

For a 204 response, clear Response media type. The exported response keeps its description and has no content object.

OpenAPI 3.1.1 — Response object

Common questions

Can I write a complete URL in Path template?

Use a path beginning with a slash. Put host information in the server configuration of the larger API document when you assemble it.

What does the generated object schema describe?

It declares that the response is an object. Add property names and detailed constraints in your API project when they are known.

Sources

Put it into practice.

Related guides