API documentation with OpenAPI/Swagger — endpoint descriptions, request/response
66
57%
Does it follow best practices?
Impact
100%
1.06xAverage score across 3 eval scenarios
Passed
No known issues
{
"context": "Tests whether the agent uses the Express-specific documentation toolchain: swagger-jsdoc for @openapi JSDoc annotations on route handlers and swagger-ui-express mounted at /api-docs, plus whether error responses and parameter documentation meet the skill requirements.",
"type": "weighted_checklist",
"checklist": [
{
"name": "swagger-jsdoc dependency",
"description": "package.json lists `swagger-jsdoc` as a dependency",
"max_score": 10
},
{
"name": "swagger-ui-express dependency",
"description": "package.json lists `swagger-ui-express` as a dependency",
"max_score": 10
},
{
"name": "@openapi JSDoc annotations",
"description": "At least two route handler functions have a JSDoc comment block containing `@openapi` (or `@swagger`) annotation",
"max_score": 10
},
{
"name": "swagger-ui-express mounted",
"description": "The Express app mounts swagger-ui-express using `app.use(...)` with the path `/api-docs`",
"max_score": 10
},
{
"name": "Error responses in annotations",
"description": "At least one @openapi annotation includes a response with a 4xx or 5xx status code",
"max_score": 10
},
{
"name": "Request body schema in annotations",
"description": "The annotation for the create booking endpoint includes a `requestBody` schema with field names",
"max_score": 8
},
{
"name": "Required fields in schema",
"description": "At least one @openapi requestBody schema uses the `required` array to distinguish required from optional fields",
"max_score": 10
},
{
"name": "Query parameter documented",
"description": "The list venues annotation includes at least one `in: query` parameter entry",
"max_score": 8
},
{
"name": "Path parameter documented",
"description": "An annotation for an endpoint that takes a venue or booking ID includes an `in: path` parameter entry",
"max_score": 8
},
{
"name": "README mentions /api-docs",
"description": "README.md mentions `/api-docs` as the URL where interactive documentation can be accessed",
"max_score": 8
},
{
"name": "All four routes implemented",
"description": "Source code includes routes for: list venues, get venue by ID, create booking, cancel booking",
"max_score": 8
}
]
}