oxidecomputer / oxidecomputer/openapi-lint
want error message for non-pascal-case type names to suggest `schemars` interpolation for generic types
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 12
- Forks
- 4
- PR merge metrics
- No merged PRs in 30d
Description
I was recently tripped up by the discovery that the default schema names that schemars generates for generic types are not PascalCase and are therefore rejected by openapi-lint (and opened #28). After doing some digging, I discovered that this was previously discussed in #14, and can be resolved using the #[schemars(rename = "...")] attribute, with the generic type parameter interpolated into a format-string-like syntax. See, for example, https://github.com/oxidecomputer/omicron/commit/775f9aa5c63382887092d852452f3719084fba9f.
Currently, though, the lint output for this only suggests the #[serde(rename = "...")] attribute, and not the schemars version; and as demonstrated by my flailing in the replies to #28, this doesn't solve the problem:
error: Generated OpenAPI document for API "nexus-lockstep" version 0.0.1 is not valid: OpenAPI document
validation failed:
The type "Setting_for_Boolean" has a name that is not PascalCase; to rename it add #[serde(rename
= "SettingForBoolean")]
For more info, see https://github.com/oxidecomputer/openapi-lint#naming
The type "Setting_for_NonZeroU32" has a name that is not PascalCase; to rename it add
#[serde(rename = "SettingForNonZeroU32")]
For more info, see https://github.com/oxidecomputer/openapi-lint#naming
It would be nice if the lint itself, or at least the docs it links to, suggested the correct thing. For instance, it could look for the _for_ pattern in a schema name and say something like:
error: Generated OpenAPI document for API "nexus-lockstep" version 0.0.1 is not valid: OpenAPI document
validation failed:
The type "Setting_for_Boolean" has a name that is not PascalCase; to rename it add #[serde(rename
= "SettingForBoolean")]
note: This looks like it might have been a generic type. Use the `#[schemars(rename = "...")]`
attribute and interpolate the generic type parameter into the format string.
or something
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 naming-rule validation that emits the shown non-PascalCase error, then review issues #14 and #28 and the linked openapi-lint naming documentation. Compare the current serde suggestion with schemars generic-name interpolation. Done means the lint or its linked documentation clearly points users to the schemars rename approach for generic types.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- tooling
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 64/100