It's possible to author your API outside of ClickHelp and update a single file, and then render it with Swagger UI right inside the Reader UI, alongside other documentation.
How to Implement
- Download Swagger UI repo: https://github.com/swagger-api/swagger-ui.
- Unzip the archive on your local machine. You’ll need to look inside the dist folder.
- Find there and upload the following files into your ClickHelp Storage (note that there are 3 tabs at the top of the File Manager, so CSS will need to be uploaded via the Styles tab and .js files via the Scripts tab):
- swagger-ui.css
- swagger-ui-bundle.js
- swagger-ui-standalone-preset.js
- Upload your .yaml file into the Storage as well via the Images&Files tab of the File Manager.
Note Don't place the .yaml file into the project's folder, because it will not be accessible due to security settings. - Add the following HTML to the Additional tags section of the Master Page section. You can do this for a single project or the whole portal if you want this to be applied for all of your projects:HTML
<link rel="stylesheet" type="text/css" href="swagger-ui.css">
/* Be sure to replace the link to the respective CSS file in your ClickHelp storage*/ - Open the topic in your project, switch to the Source mode and add this:HTML
<div id="swagger-ui"></div>
/*Replace the links to script files to the respective files in your ClickHelp storage */
<script src="swagger-ui-bundle.js"></script>
<script src="swagger-ui-standalone-preset.js"></script>
<script>
window.onload = function() {
const ui = SwaggerUIBundle({
//Make sure the link points to your yaml file in your project folder
url: "https://yourportal.clickhelp.co/resources/Storage/yourfile.yaml",
dom_id: '#swagger-ui',
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
]
})
window.ui = ui
}
</script>
After this, unlock the topic (you will see nothing in the editing mode, as all scripts are disabled). When the script loads, you should see Swagger UI and your content loaded.
Going on, you won’t have to touch the topic – only replace the .yaml file in the Storage with the updated one.