Project

Profile

Help

Issue #5009

HTML in our json api schema

Added by daviddavis 10 months ago. Updated 4 months ago.

Status:
CLOSED - CURRENTRELEASE
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 7 months 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 7 months ago

Filter out html by default in REST API docs

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

History

#1 Updated by daviddavis 10 months ago

  • Description updated (diff)

#2 Updated by daviddavis 10 months ago

  • Description updated (diff)

#3 Updated by daviddavis 10 months ago

  • Description updated (diff)

#4 Updated by daviddavis 10 months ago

  • Description updated (diff)

#5 Updated by dkliban@redhat.com 9 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 9 months ago

  • Sprint changed from Sprint 55 to Sprint 56

#7 Updated by daviddavis 8 months ago

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

#8 Updated by rchan 8 months ago

  • Sprint changed from Sprint 56 to Sprint 57

#9 Updated by rchan 7 months ago

  • Sprint changed from Sprint 57 to Sprint 58

#10 Updated by rchan 7 months ago

  • Sprint changed from Sprint 58 to Sprint 59

#12 Updated by daviddavis 7 months ago

  • Status changed from POST to MODIFIED

#13 Updated by bmbouter 4 months ago

  • Sprint/Milestone set to 3.0.0

#14 Updated by bmbouter 4 months ago

  • Status changed from MODIFIED to CLOSED - CURRENTRELEASE

Please register to edit this issue

Also available in: Atom PDF