Issue #5009

Updated by daviddavis almost 5 years ago

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 <code>less</code> our api json docs to now use the generated html docs instead. I prefer to stick to the CLI 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.