Use operationId for #anchor tags of REST API endpoint titles
#139
Comments
|
Would making this change mean we'd be breaking anchor links people already have bookmarked and if so, are we OK with that? |
|
I think we could pretty easily add invisible companion anchors to continue supporting the old slugs. |
|
The obvious idea. Good thinking. Let's do both! So the old ones still work. But make the Operation ID URLs the default for anything that links to those sections. |
|
This issue is stale because it has been open 60 days with no activity. |
|
Still planning todo. Just taking time to get to it. Other priorities. |
|
@nschonni this one may be worth looking at if you decide to spend more time making improvements to the codebase! |
|
This issue is stale because it has been open 60 days with no activity. |
|
This issue is stale because it has been open 60 days with no activity. |
This comment was marked as spam.
This comment was marked as spam.
This comment was marked as spam.
This comment was marked as spam.
|
Hi everybody! As I can see, this issue is not resolved. Can I work on it? |
|
I suspect it would be fine to simply switch to using the "summary key" as long as there are no duplicates on any page. I don't think we need to add "invisible companion anchors" for the current hashes, I'm concerned about added complexity and maintenance doing that. We would be happy to have an open source contributor help with this task, as we will likely not prioritize this internally. |
and others
What feature or product is affected?
What is the new or expected behavior?
Example
would become
See OpenAPI spec at https://github.com/github/openapi/blob/347c7c385184352692d4118b7e8a266ccf9b7db7/definitions/operations/repos/check-vulnerability-alerts.yml#L6
How is the old or inaccurate behavior currently documented?
n/a
Who does this affect?
Every change to an
#anchorname for endpoint titles requires a change in the code, due to the error handlers which include a URL to the documentation. The endpoint titles are more prone to changes, while operation IDs should be changed much less frequently, as they are consider a breaking change to some of the OpenAPI consumers, while the"summary"key is not.The problem with the title changes might also be amplified once translations are introduced.
@zeke sent me here, we shortly discussed it today:
What is the impact to users?
n/a
Content strategy and implementation
tbd
The text was updated successfully, but these errors were encountered: