search

bcgov / DBC-APIM

DataBC OPEN API Services
Apache License 2.0
1 stars 0 forks source link

HTML rendering #34

Closed BK01 closed 7 years ago

BK01 commented 7 years ago

Skills / SW:

Description:

Deliverables:

banders commented 7 years ago

I forked swagger-ui and created a branch to address this issue. The branch re-introduces support for HTML markup in response descriptions.

Note 1: we prefer HTML Markup over markdown for links because HTML markup allows us to open links in new tabs (using target="blank" in an anchor tag), whereas markdown does not.

Note 2: The swagger-ui community is phasing out support of HTML markup in API specs because of the potential XSS vulnerability. Our deployment of swagger-ui is fairly controlled, so the vulnerability shouldn't apply to us. Nevertheless, the swagger UI community is unlikely to incorporate our change, as indicated in this Issue. I'll plan to maintain my "fix" in the "support-html-rendering" branch, and we can use that to build custom versions of swagger-ui as needed.

For now I have built a custom swagger-ui dist directly from my "support-html-rendering" branch, and I have included the dist files in my fork of ckanext-openapiviewer. I have created a pull request to have the changes merged into the bcgov repo.

BK01 commented 7 years ago

@ll911 @banders UAT in cad.data was mainly successful. Example includes the links shown in the description section of the OpenAPI console. Specific to the geocoder console, the outputFormat link works, however, most others do not. I suspect the JSON file needs to be updated to use the correct HTML syntax.

If confirmed with team -> Mark this issue complete and create a new ticket to update the links in existing OpenAPI spec files (JSON).

BK01 commented 7 years ago

@banders Apply patch used for outputFormat for remainder of description hyperlinks

banders commented 7 years ago

I have extended swagger-ui to support the 'target' attribute in <a href> elements. This allows a swagger spec file to define links that open in new tabs. The patch has been committed to this branch.

banders commented 7 years ago

I incorporated the patch into a custom build of swagger-ui for ckanext-openapiviewer. Pull request is here.

BK01 commented 7 years ago

@BK01 to review this week

BK01 commented 7 years ago

UAT complete in cat.data... Ready for PROD.

BK01 commented 7 years ago

Ready to migrate to PROD.