Describe a workshop route as one OpenAPI operation
Admin ·
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.
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.
path workshopId integer required
query includeDrafts boolean optionalOpenAPI 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.
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.
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.