API API Documentation & Specification 2 — Questions and Answers
Question 1: What is a 'path parameter' in an OpenAPI Specification?
- A header sent with the request
- A variable embedded directly in the URL path, like /users/{id} (Correct answer)
- A query string appended to the URL
- A field in the request body
Correct answer: A variable embedded directly in the URL path, like /users/{id}
Path parameters are variable segments in the URL path, defined with curly braces in OpenAPI (e.g., /users/{id}), used to identify specific resources.
Question 2: What does the 'required' keyword in a JSON Schema or OpenAPI specification indicate?
- The field must be present in the request or response payload (Correct answer)
- The field is optional but recommended
- The field has a default value
- The field is read-only
Correct answer: The field must be present in the request or response payload
The 'required' array in JSON Schema/OpenAPI lists fields that must be present in the object; omitting them should result in a validation error.
Question 3: Which OpenAPI component is used to define reusable request/response schemas across multiple endpoints?
- paths
- servers
- components/schemas (Correct answer)
- info
Correct answer: components/schemas
The 'components/schemas' section defines reusable schema objects that can be referenced via $ref throughout the OpenAPI spec.
Question 4: What is Redoc used for in the API documentation ecosystem?
- Performance testing APIs
- Rendering OpenAPI specifications as clean, responsive documentation pages (Correct answer)
- Scanning APIs for security vulnerabilities
- Generating API mock servers
Correct answer: Rendering OpenAPI specifications as clean, responsive documentation pages
Redoc is an open-source tool that renders OpenAPI 2.0/3.0 specs into polished, three-panel documentation websites.
Question 5: What does 'API deprecation' mean in the context of versioning and documentation?
- Removing an API endpoint immediately
- Marking an API endpoint as outdated and scheduled for removal, while keeping it functional (Correct answer)
- Encrypting old API endpoints
- Resetting the API to its original version
Correct answer: Marking an API endpoint as outdated and scheduled for removal, while keeping it functional
Deprecation marks an endpoint or version as obsolete, warning consumers to migrate before it is eventually removed, allowing a grace period.
Question 6: What is the role of 'examples' in an OpenAPI specification?
- Show real API traffic logs
- Provide sample request and response payloads to help developers understand expected data (Correct answer)
- Define performance benchmarks
- Set rate limit values
Correct answer: Provide sample request and response payloads to help developers understand expected data
Examples in OpenAPI specs show concrete sample payloads for requests and responses, making documentation more useful and enabling mock server generation.
API API Documentation & Specification 2
What is a 'path parameter' in an OpenAPI Specification?