OpenAPI & Swagger Vocabulary
0 / 5 completed
Exercise 1 of 5
The backend engineer says: 'Each operation in our OpenAPI spec has an operationId — like listUsers, createUser, getUserById. Code generators use it to name SDK methods.'
What is an operationId in an OpenAPI specification?
operationId is a unique machine-readable string per operation. SDK generators use it for method names, documentation uses it for anchors. Always set it — without it you get names like get_users_id_get.
Exercise 2 of 5
The architect says: 'We use $ref to avoid duplication — the error schema is defined once in components/schemas and referenced everywhere.'
What does $ref do in an OpenAPI specification?
$ref (JSON Reference) points to a reusable definition in the components section. It keeps the spec DRY — define once, reference many times. Circular $refs are allowed for recursive data structures.
Exercise 3 of 5
The security engineer says: 'Our API uses Bearer token authentication — defined as a securityScheme of type http with scheme bearer, then referenced in each protected operation.'
Where are authentication schemes defined in an OpenAPI spec?
SecuritySchemes are defined in components/securitySchemes (Bearer, OAuth2, API key, OpenID Connect), then applied globally or per-operation using the security field.
Exercise 4 of 5
The team discusses: 'Path parameters are part of the URL like /users/42. Query parameters come after the ? like /users?role=admin. Both are defined in the parameters array.'
What is the difference between a path parameter and a query parameter in OpenAPI?
Path parameters (in: path) are embedded in the URL and always required. Query parameters (in: query) are appended after ? and can be optional. Both are declared in the parameters array with their name, in, required, and schema fields.
Exercise 5 of 5
The developer says: 'We use Swagger UI for internal testing and Redoc for the public developer portal — both generated from the same OpenAPI YAML file.'
What is the main difference between Swagger UI and Redoc?
Swagger UI lets developers make real API calls from the browser (try-it-out). Redoc generates a polished three-panel reference site better suited for public developer portals. Both consume the same OpenAPI spec.