feat(specs): improve API reference documentation #2831
Conversation
Make the API reference a little nicer with things like sorting parameters and enums alphabetically.
✗ The generated branch has been deleted.If the PR has been merged, you can check the generated code on the |
|
There's a type error with Go because of the update for the "Search dictionary" response. No idea how to fix this. |
specs/search/paths/dictionaries/common/schemas/SearchDictionaryEntriesResponse.yml
Show resolved
Hide resolved
|
This is a massiveeeee improvement thanks a lot @kai687 |
specs/common/parameters.yml
Outdated
|
|
||
| ForwardToReplicas: | ||
| in: query | ||
| name: forwardToReplicas | ||
| description: Indicates whether changed index settings are forwarded to the replica indices. | ||
| description: Whether changes are applied to replica indices. | ||
| schema: | ||
| type: boolean | ||
|
|
||
| Page: | ||
| in: query | ||
| name: page | ||
| description: > |
There was a problem hiding this comment.
I think we can replace all > with pipes to preserve formatting, wdyt?
There was a problem hiding this comment.
Done it for the Search API and common. Will do it for the rest in separate PRs when updating the docs for the other APIs.
Curiously, the | doesn't appear in the bundled specs. Something in the process of formatting and writing the spec changes this. I couldn't find any formatting artifacts on the website due to this, so I'm not sure what's going on here.
| description: For compound entries, governs the behavior of the `word` parameter. | ||
| example: ['kopf','schmerz','tablette'] | ||
| description: Invividual components of a compound word in the `compounds` dictionary. | ||
| example: [kopf, schmerz, tablette] |
There was a problem hiding this comment.
We should keep quotes since it's an array of string, no?
There was a problem hiding this comment.
Is that what YAML requires? I thought quotes are only needed if you have special characters like - or : in the string. I thought that plain words don't require quotes. But since they also don't hurt, we might also leave them in.
There was a problem hiding this comment.
I think it's ok to not quote it. Couldn't find anything that breaks because of this. The response example renders correctly as strings.
|
Here's my reference for the |
shortcuts
changed the title
🧭 What and Why
To make the OpenAPI-generated docs ready to replace the main API reference docs,
add more information from the API methods and API parameters docs.
🎟 JIRA Ticket:
Changes included:
searchDictionaryEntriesresponseattributesForFacetingcan only be used as index setting, not as search parameter.explainAPI parameter is not supposed to be exposed.