oxidecomputer / oxidecomputer/dropshot
Use components for common params in OpenAPI spec
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 1.2k
- Forks
- 104
- Avg merge
- 1d 19h
- Merged PRs (30d)
- 22
Description
I noticed in the Omicron OpenAPI spec that this block of pagination params appears about 25 times (with slight variations around sort mode). Obviously improving the human-readability and length of a machine-oriented spec is not particularly urgent, but it looks like this could be shortened quite a bit with global components.
"parameters": [
{
"in": "query",
"name": "limit",
"description": "Maximum number of items returned by a single call",
"schema": {
"nullable": true,
"type": "integer",
"format": "uint32",
"minimum": 1
},
"style": "form"
},
{
"in": "query",
"name": "page_token",
"description": "Token returned by previous call to retrieve the subsequent page",
"schema": {
"nullable": true,
"type": "string"
},
"style": "form"
},
{
"in": "query",
"name": "sort_by",
"schema": {
"$ref": "#/components/schemas/IdSortMode"
},
"style": "form"
}
],
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the Omicron OpenAPI spec at openapi/nexus.json#L20-L51 and compare the repeated pagination parameter blocks, including the sort-mode variations. Trace how Dropshot generates this spec, then move common parameters into OpenAPI components and replace repeated definitions with references. Done means the generated spec is shorter, preserves the variations, and remains valid.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi, rust
- Domain
- api, backend-api-design
- Issue type
- Refactor
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100