PaloAltoNetworks / PaloAltoNetworks/docusaurus-openapi-docs

Support showing openapi Links

Open
#938 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
TypeScript
Stars
1.1k
Forks
315
Avg merge
7d 5h
Merged PRs (30d)
7

Description

Is your feature request related to a problem?

When the api response is returning an identifier for a field and it is linked to another operation in the schema, I want to show that clearly so that the api users can understand that they can use this response info to fetch more information by calling related/linked operations.

See the open api link specification:

https://spec.openapis.org/oas/latest.html#link-object

And the swaager docs:

https://swagger.io/docs/specification/links/

Describe the solution you'd like

Initially just show the links like swagger docs does:

Screenshot from 2024-08-28 14-17-20

Later somehow use links to allow staging another operation.

Describe alternatives you've considered
  • Provide sub resources directly as nested objects
Additional context

I'm trying to make it easy to explain to users that they can fetch nested information by making another request to fetch sub resources.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading the OpenAPI Link Object specification and the Swagger links documentation, then inspect how this project currently renders API responses and related operations. Done means generated API documentation visibly shows links from response fields to related operations; the later operation-staging idea is outside the initial scope.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, react, typescript
Domain
documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.