enum openapi descriptions
jessfraz opened this issue · 8 comments
This is a nice to have but in the OpenAPI spec since individual items in an enum don't have a "description" field would be cool, if JSONSchema or whatever the backend is here, took all those individual comments and made one much longer description for the entire summary including them
cc @ahl for if this is possible
For sure, but I'm not 100% clear on what you're looking for here. Can you post an example in rust the approximate output we'd like to have?
okay so say the given rust code is, ignore the shitty indents:
/// My little enum does this thing and that.
pub enum MyLittleEnum{
// Red pill does one thing.
RedPill
// Blue pill does another.
BluePill
}
So since the OPen API spec for an enum doesn't have descriptions for each value something like this could be created instead for the entire enum:
My little enum does this thing and that.
- `RedPill`: Red pill does one thing.
- `BluePill`: Blue pill does another.
if they dont have descriptions we could just ignore it but if they do I just don't want to lose the data
i guess this only applies to enums of strings that become that type of spec if that makes sense, I think the anyofs or whatever would keep the data
I see, so when we have a simple, externally tagged enum where it essentially boils down to:
{
"type": "string",
"enum": [ "RedPill", "BluePill" ]
}Agreed that we lose the doc comments that we'd otherwise get if the enum were, say, internally tagged. I'm going to poke at schemars to see what the derive macro is doing in this case.
Is there a particular nexus type where we have good docs for the enum variants that are being discarded? Or is this for another API?
I'm not sure if they have them already but the ones for roles would be nice to have docs on each like FleetRoles, OrganizationRoles, ProjectRoles, etc
See GREsau/schemars#152. It would be challenging to fix this without support from schemars; if we can't get traction we'll fork the repo.
