fix(api-reference): ranking explicit title declaration as highest friendly name #6953
Conversation
When a `title` is given, it should be given the highest precedence for use in a friendly name since it's explicity stated and that is the purpose of `title`. Closes scalar#6952
🦋 Changeset detectedLatest commit: 0e69342 The changes in this PR will be included in the next version bump. This PR includes changesets to release 8 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
There was a problem hiding this comment.
Hey thanks for the quick PR! It works for me (@hanspagel ?)
also should we bump down const or just delete it? I'm not sure I see the value
amritk
changed the title
…osing a friendly name for `anyof`
There was a problem hiding this comment.
Thanks for taking the time to submit this PR! We should also keep in mind that fastapi users get a title as a default for all types:
Sooo it might be a little bit more complex to serve everyone well.
Just a quick feedback from me, I’ll think about a good solution.
Got it, was thinking there had to be a reason for it to be this way originally. Just a thought--shouldn't this be as tool-agnostic as possible? I haven't used fastapi in ages, but from a design philosophy isn't it more strange that fastapi provides titles that aren't meant for display purposes? IE: from my naive vantage point it seems more like a fastapi limitation than a scalar one. |
|
I agree in theory. In practive, I also have to accept that it’s the reality (and won’t change) and the FastAPI user base is huge. Everyone deserves a beautiful API reference. |
Titles are meant for display purposes but they are not the same as types (even in the OpenAPI spec). There are three pieces of data:
The former two are required to use an API correctly. The last one is a nice to have. It can't be used to replace either of the above two (especially not in a scalar case, such as for query parameters). |
|
@tibbe yep |
5 participants
When a
titleis given, it should be given the highest precedence for use in a friendly name since it's explicity stated and that is the purpose oftitle.Closes #6952
Problem
Currently, even when you use
titleto give your dropdown a friendly name, it wont be used (see #6952).Solution
titleis given the highest precedence since it is explicitly used as a friendly name by the user.Checklist
I've gone through the following:
pnpm changeset).Note
Prioritizes
titleover types/arrays/xml/const when computing schema friendly names and updates tests; adds changeset for minor release.get-schema-type.ts:titleis used first for friendly names (before const, arrays, xml.name, contentEncoding, refs, raw type).titlewhen present (e.g.,array Mixed Item[]).get-schema-type.test.ts):titleover array unions and in complex schemas.itemsare defined; add case for item titles within arrays.@scalar/api-reference; note thattitlehas highest precedence foranyof.Written by Cursor Bugbot for commit 0e69342. This will update automatically on new commits. Configure here.