Project

Profile

Help

Task #4104

Add index and headings to REST API docs

Added by dkliban@redhat.com 12 months ago. Updated 6 months ago.

Status:
MODIFIED
Priority:
Normal
Category:
-
Sprint/Milestone:
Start date:
Due date:
% Done:

0%

Platform Release:
Blocks Release:
Backwards Incompatible:
No
Groomed:
Yes
Sprint Candidate:
Yes
Tags:
Documentation
QA Contact:
Complexity:
Smash Test:
Verified:
No
Verification Required:
No
Sprint:
Sprint 51

Description

The REST API docs for pulpcore are very long and hard to navigate. The page could use an index and some headings to seperate the docs into sections.


Related issues

Related to Pulp - Test #4123: Test the generated API binds MODIFIED Actions

Associated revisions

Revision f5a1d28c View on GitHub
Added by dkliban@redhat.com 6 months ago

Problem: OpenAPI schema test is unreliable between different installs

Solution: Remove the test

re: #4104
https://pulp.plan.io/issues/4104

Revision e817af65 View on GitHub
Added by dkliban@redhat.com 6 months ago

Problem: REST API docs are poorly organized

Solution: Break up REST API docs into sections

This patch modifies the OpenAPI schema. It introduces the concept of Tags. Each tag represents a type
of resource in Pulp. E.g. Artifacts, Content, Remotes, Publishers, etc.

This patch also improves the 'summary' field for each operation also. This is achieved with a new
custom inspector class that drf_yasg can use to build the OpenAPI schema.

This patch also adds a new 'restapi.html' page to the static docs. This new page uses ReDoc and the
OpenAPI schema to display the REST API docs.

re: #4104
https://pulp.plan.io/issues/4104

History

#1 Updated by daviddavis 12 months ago

  • Groomed changed from No to Yes
  • Sprint Candidate changed from No to Yes

#2 Updated by amacdona@redhat.com 12 months ago

Can we also s/REST API Integration/Web API/ since we will be making an index.

Since the API is not just for integrators, but for users I think this makes more sense. Also, just to be a stickler, we are pretty RESTful, but I prefer to avoid the term if we aren't fully compliant. If this is controversial, ignore it, no reason to slow the main purpose of this.

#3 Updated by dkliban@redhat.com 12 months ago

  • Sprint set to Sprint 45

#4 Updated by rchan 11 months ago

  • Sprint changed from Sprint 45 to Sprint 46

#5 Updated by rchan 9 months ago

  • Sprint changed from Sprint 46 to Sprint 47

#6 Updated by rchan 9 months ago

  • Sprint changed from Sprint 47 to Sprint 48

#7 Updated by rchan 8 months ago

  • Sprint changed from Sprint 48 to Sprint 49

#9 Updated by rchan 7 months ago

  • Sprint changed from Sprint 49 to Sprint 50

#10 Updated by rchan 7 months ago

  • Sprint changed from Sprint 50 to Sprint 51

#11 Updated by dkliban@redhat.com 6 months ago

  • Status changed from NEW to ASSIGNED

#13 Updated by kersom 6 months ago

  • Related to Test #4123: Test the generated API binds added

#14 Updated by dkliban@redhat.com 6 months ago

  • Status changed from POST to MODIFIED

#15 Updated by ipanova@redhat.com 6 months ago

  • Assignee set to dkliban@redhat.com

#16 Updated by daviddavis 6 months ago

  • Sprint/Milestone set to 3.0

#17 Updated by bmbouter 6 months ago

  • Tags deleted (Pulp 3)

Please register to edit this issue

Also available in: Atom PDF