oxidecomputer / oxidecomputer/openapi-lint

want error message for non-pascal-case type names to suggest `schemars` interpolation for generic types

Open
#29 0 comments 0 reactions 0 assignees View on GitHub

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

  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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.