Project

Profile

Help

Issue #5009

HTML in our json api schema

Added by daviddavis 4 months ago. Updated 27 days ago.

Status:
MODIFIED
Priority:
Normal
Assignee:
Category:
-
Sprint/Milestone:
-
Start date:
Due date:
Severity:
2. Medium
Version:
Platform Release:
Blocks Release:
OS:
Backwards Incompatible:
No
Triaged:
Yes
Groomed:
No
Sprint Candidate:
No
Tags:
QA Contact:
Complexity:
Smash Test:
Verified:
No
Verification Required:
No
Sprint:
Sprint 59

Description

I noticed some strange descriptions for actions in our api schema when viewing it as json. I'm hitting the /pulp/api/v3/docs/api.json endpoint and seeing:

<!-- User-facing documentation, rendered as html-->\nFileRemote represents an external source of <a href=\"#operation/content_file_files_list\">File\nContent</a>.  The target url of a FileRemote must contain a file manifest, which contains the\nmetadata for all files at the source.

I wonder if we should avoid including html in fields as our api schema since it can be rendered in many different forms (e.g. json).

I see a few downsides to having HTML in our api schema:

1. This forces me and pulp users like me who prefer to less our api json docs to now use the generated html docs instead. I prefer to stick to the command line whenever possible.
2. Tools may eventually read/display these descriptions. I am thinking of potential tools like a pulp cli, tools that generate stuff like bash scripts or ansible roles, etc.
3. Other tools that can generate HTML like a Pulp web UI may not be able to properly generate this html. Stuff like links may not work properly.

Associated revisions

Revision a7a7f53a View on GitHub
Added by daviddavis 27 days ago

Add include_html flag to generation of plugin REST API docs

ref #5009
https://pulp.plan.io/issues/5009

Revision d615f23a View on GitHub
Added by daviddavis 27 days ago

Filter out html by default in REST API docs

fixes #5009
https://pulp.plan.io/issues/5009

History

#1 Updated by daviddavis 4 months ago

  • Description updated (diff)

#2 Updated by daviddavis 4 months ago

  • Description updated (diff)

#3 Updated by daviddavis 4 months ago

  • Description updated (diff)

#4 Updated by daviddavis 4 months ago

  • Description updated (diff)

#5 Updated by dkliban@redhat.com 4 months ago

  • Triaged changed from No to Yes
  • Sprint set to Sprint 55

We will add a query argument call 'include_html' which will cause the OpenAPI schema to be returned with HTML tags. If this argument is not included i nthe request to /pulp/api/v3/docs/api.json, the HTML is not included.

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

  • Sprint changed from Sprint 55 to Sprint 56

#7 Updated by daviddavis 2 months ago

  • Status changed from NEW to ASSIGNED
  • Assignee set to daviddavis

#8 Updated by rchan 2 months ago

  • Sprint changed from Sprint 56 to Sprint 57

#9 Updated by rchan about 2 months ago

  • Sprint changed from Sprint 57 to Sprint 58

#10 Updated by rchan about 1 month ago

  • Sprint changed from Sprint 58 to Sprint 59

#12 Updated by daviddavis 27 days ago

  • Status changed from POST to MODIFIED

Please register to edit this issue

Also available in: Atom PDF