oxidecomputer / oxidecomputer/dropshot

Use components for common params in OpenAPI spec

Open
#386 1 comment 0 reactions 0 assignees View on GitHub

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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.