pulp / pulp/pulp-docs

Use more Redoc render features (REST API)

Open
#88 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
HTML
Stars
2
Forks
17
Avg merge
7d 18h
Merged PRs (30d)
3

Description

Problem

The Redoc API render engine has some under-used features (attached below).

Approach

Actually, the changes that can make it better may not belong to pulp-docs itself, but I'll put here to expose the big picture.
We should investigate how we can change DRF/spectacular/??? to make use of those.

To test the API website that originated the snapshots, run the code below.
Notice the relevant schema reference is this.

podman pull redocly/redoc  # from docker registry
podman run --rm \
    -p 8080:80 \
    -e SPEC_URL=https://raw.githubusercontent.com/Redocly/redoc/refs/heads/main/demo/openapi.yaml \
    redocly/redoc

Snapshots

Section groups

We can use sections like "Content Management", "Auth", "Admin", etc.
An opportunity to logically group pulp entities from the user perspective.

image

Text Sections

We can write text section that appear in the navigation.
This can be used for presenting useful links and info.

Some ideas:

Listing links to supported API pages (and provide the Redoc for those, of course):

## Supported versions

- [3.39](site:pulpcore/restapi/3.39/)
- [3.22](site:pulpcore/restapi/3.22/)
- [3.21](site:pulpcore/restapi/3.21/)

Shortcut links to other plugin API docs:

## Other plugins

[pulp_file](...) - [pulp_python](...) - [pulp_rpm](...) - etc

image

Deprecated field and endpoint

Just looks better and more obvious that you shouldn't use it.

image

image

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 with the linked Redoc demo/openapi.yaml and run the provided podman redoc container command to inspect the referenced render features. Investigate whether the required changes belong in pulp-docs, DRF, or spectacular. Done would require an agreed scope and API documentation demonstrating selected section groups, text sections, or deprecated fields and endpoints.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi
Domain
api, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.