How to embed a link into each operation in Swagger UI

[Cloudmersive]

Q&A (please complete the following information)

• OS: Windows 10 / Mac OS Latest
• Browser: Chrome Latest
• Version: Latest
• Method of installation: Dist Assets
• Swagger-UI version: Latest
• Swagger/OpenAPI version: Swagger 2.0

Content & configuration

You can see it here: https://api.cloudmersive.com/swagger/index.html?urls.primaryName=Image%20Recognition%20and%20Processing%20API

Swagger/OpenAPI definition (JSON):
https://api.cloudmersive.com/swagger/api/image

Swagger-UI configuration options:

SwaggerUI({
  // your config options here
})

var configObject = JSON.parse('{"urls":[{"url":"/swagger/api/convert","name":"Convert API"},{"url":"/swagger/api/nlp","name":"Natural Language Processing (NLP) API"},{"url":"/swagger/api/ocr","name":"Optical Character Recognition (OCR) API"},{"url":"/swagger/api/validate","name":"Validate API"},{"url":"/swagger/api/virus","name":"Virus Scan API"},{"url":"/swagger/api/image","name":"Image Recognition and Processing API"},{"url":"/swagger/api/barcode","name":"Barcode API"},{"url":"/swagger/api/speech","name":"Speech API"}],"validatorUrl":null}');
--
  | var oauthConfigObject = JSON.parse('{}');
  |  
  | // Apply mandatory parameters
  | configObject.dom_id = "#swagger-ui";
  | configObject.presets = [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset];
  | configObject.layout = "StandaloneLayout";
  |  
  | // If oauth2RedirectUrl isn't specified, use the built-in default
  | if (!configObject.hasOwnProperty("oauth2RedirectUrl"))
  | configObject.oauth2RedirectUrl = window.location.href.replace("index.html", "oauth2-redirect.html");
  |  
  | configObject.onComplete = function () {
  | // Here, "basicAuth" and "apiKey" are the security scheme names/keys in the "securityDefinitions" collection
  | ui.preauthorizeApiKey("Apikey", "28e63794-ef8a-4616-80bb-26fdd3709a19");
  |  
  |  
  | };
  |  
  | // Build a system
  | const ui = SwaggerUIBundle(configObject);

Screenshots

You can see it running here: https://api.cloudmersive.com/swagger/index.html?urls.primaryName=Image%20Recognition%20and%20Processing%20API

How can we help?

We want to add a hyperlink to each Operation that links contextually to help documentation with more information, so ideally it is a parameterized link that includes the ID or name of the operation.

Hopefully this is simple to do - what is the best way to do it? We tried with the documented JS APIs but were not able to get this to work.

Any help with this is greatly appreciated!

[shockey]

hi @Cloudmersive - is there any reason you can't add a Markdown link to each operation's description? or are you looking for an automated solution that generates similar links for each operation?

[Cloudmersive]

@shockey Thanks for the quick response. Yes, we are looking for an automated solution. Also, we wanted to actually make it a bit more elaborate over time where the link ultimately became an iFrame or embedded UX element that allows users to look through generated code examples in various SDK languages. We currently offer this in our static docs (example: https://api.cloudmersive.com/docs/image.asp ) via an iframe and would similarly like to be able to embed an iframe into each of the operations.

Is there an easy way to do this via the swagger-ui extension APIs? We were struggling to find a good way to do this so any help is greatly appreciated.

[Cloudmersive]

Any suggestions @shockey ?

[shockey]

@Cloudmersive sure, this isn't too hard!

Plugin code

const CloudmersiveCodeExamplesAfterResponsesPlugin = () => ({
  wrapComponents: {
    responses: (Responses, { React }) => (props) => {
      return React.createElement("div", null,
        React.createElement(Responses, props),
        React.createElement("iframe", { 
          src: "https://docs.cloudmersive.com", // `props.path` and `props.method` are available here so you can identify the operation
          width: "100%",
          height: "300px"
        })
      );
    }
  }
})

Result

The only gotcha here is that this won't render if an operation has no responses defined (which would make it invalid).

[Cloudmersive]

Awesome answer, thanks @shockey ! Much appreciated.

You can see the deployed result here: https://api.cloudmersive.com/swagger/index.html?urls.primaryName=Image%20Recognition%20and%20Processing%20API

[shockey]

Glad I could help, @Cloudmersive! Looks great 😄