Documenting x-state in the help center #319
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -24,6 +24,46 @@ This custom property allows you to identify some components of your | |
| documentation as beta. Find out more in our [dedicated | ||
| section](/help/specification-support/doc-beta). | ||
|
|
||
| ## Give precision to the state of your features (`x-state`) | ||
|
|
||
| This custom property can be added inside an operation or a property to identify it with a custom tag. | ||
|
There was a problem hiding this comment. I might have added some contextual elements around the feature, such as use cases or examples of how it could be valuable. There was a problem hiding this comment. We have the use cases from this week's lead. |
||
| The `x-state` property is a string. | ||
|
|
||
| ### Example usage | ||
|
|
||
| Here under is an example of an operation and a property with a `x-state`. | ||
|
|
||
| ```yaml | ||
| paths: | ||
| /diffs: | ||
| post: | ||
| tags: ["x-state"] | ||
| description: Create a diff between any two given API definitions | ||
| x-state: Technical preview # x-state flag at the operation level | ||
| requestBody: | ||
| description: The diff creation request object | ||
| content: | ||
| application/json: | ||
| schema: | ||
| type: object | ||
| properties: | ||
| url: | ||
| type: string | ||
| format: uri | ||
| x-state: Still unstable # x-state flag at the object property level | ||
| description: | | ||
| **Required** if `definition` is not present. | ||
| Current definition URL. It should be accessible through HTTP by Bump.sh servers. | ||
| ``` | ||
|
|
||
| Adding or removing this property is a structural change. | ||
|
There was a problem hiding this comment.
I recommend that we clarify what this means and what is the impact. There was a problem hiding this comment. So we would have to do the same for beta (I took this sentence from there). |
||
| When combined with the `x-beta`, the `x-state` replaces its value, but keeps the beta behavior: a change in a beta component is never identified as a breaking change. | ||
|
|
||
| The documentation displays custom tags on the operation and property: | ||
|
|
||
|  | ||
|
|
||
|
|
||
| ## Get feedback from users (`x-feedbackLink`) | ||
|
|
||
| This custom property allows you to add a button to your documentation that enables you to collect feedback from your users. Find out more in our [dedicated | ||
|
|
||
|
There was a problem hiding this comment. If you share a link to this example, I may be able to suggest a better screenshot. For instance, I could check if it’s the right dimensions, follows the appropriate template, and perhaps add a highlight to emphasize the badge. There was a problem hiding this comment. I sent you the API, if you want a better image 😌 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think the wording could be more impactful here.
Our users have often referred to this feature as “badges.” Therefore, I’d lean towards something like “Operation Status Badges”, “Endpoint Status Badges", or even "Status Badges". Or maybe something around "tag" ?
It should be something easily searchable using terms like “status” or “badge.”
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I fully agree that it should be mentioned up there!
As of 'tags' or 'badges', you're also right. Badges are tags you can't interact with. So we should harmonize to 'badges' everywhere.