Swagger-ui: 'external-docs' reference not rendered by swagger ui

[shashi0905]

I am having problem with the 'external-docs' element, First, I tried to include an external-docs reference through swagger annotations (swagger 2.0) on my java code. While all other annotations worked fine, the @ExternalDocs annotation just refused to get included into the generated json file.
[ Annotation Ref :

@GET 
@Path("/v2/hotspots") 
@Produces(MediaType.APPLICATION_JSON) 
@ExternalDocs(value="Common Error Codes", url = "some url") 
@ApiOperation(....)
@ApiResponses(....)
public final Response someMethod( )  ] 

Then I tried to do the swagger configuration at code level
[ Code Ref :

ExternalDocs exterDoc = new ExternalDocs();
exterDoc.setDescription("Common Error Codes");
exterDoc.setUrl("some url");

Swagger swag = new Swagger();
swag.externalDocs(exterDoc);
beanConfig.configure(swag ); ]

But It didn't work either. There was no reference of external docs that i was looking for.

Then, I tried to manually write a json file so that I have the required external-docs on my swagger UI

What I am getting currently :

What I want to have :

I want an html link to an external URL below the model definitions.
I put an external-docs reference into my json file (taking reference from the json used in the above swagger UI definition) -

"error_def":
{
...........................
.... properties.....
"externalDocs":
{
"description": "List of error codes",
"url": "someURL"
},
...............................
}

Still I do not get any external doc reference on swagger UI.
Do I need to modify the index.html file to insert an html link to external reference like this ?

[webron]

The issue is not closed?

[fehguy]

@webron I think he's saying that it doesn't work, so it probably shouldn't be closed.

[deckar01]

externalDocs is rendered by the main template, which only covers the main swagger object.

There are four objects that allow external documentation:

• Swagger Object
• Operation Object
• Tag Object
• Schema Object

The fix may be as simple as inserting the same template logic after each section's description. https://github.com/swagger-api/swagger-ui/commit/3e9ef05 introduced the original implementation for the main swagger object.

{{#if externalDocs}}
<p>{{externalDocs.description}}</p>
<a href="{{externalDocs.url}}" target="_blank">{{externalDocs.url}}</a>
{{/if}}

Templates:

• [x] [main](https://github.com/swagger-api/swagger-ui/blob/a98f891/src/main/template/main.handlebars) (Swagger Object)
• [ ] [operation](https://github.com/swagger-api/swagger-ui/blob/a98f891/src/main/template/operation.handlebars) (Operation Object)
• [ ] [signature](https://github.com/swagger-api/swagger-ui/blob/a98f891/src/main/template/signature.handlebars) (Schema Object)

It appears that the tags field is not rendered in any templates. They can be specified on both swagger objects and operation objects. Tags are usually rendered inline as text bubbles, but since the swagger tag objects can have descriptions and external docs, a list-like structure may be more suitable. (Tags are used for grouping already, and the description is ignored, so there is probably no need for tag level external docs)

@fehguy @webron I can open a PR for the operation and signature templates and punt the tags to their own issue if you are interested in landing support for external documentation.

[dklotz]

@deckar01 The description of tags is not ignored, its the text that gets printed to the right of the tag name in the ui ("API methods to work with documents" in this screenshot):

And since the specification (and the @Tag annotation inside e.g. the @SwaggerDefinition) allows for external docs on the tag object, I for one would love to be able to provide external docs for all the methods grouped under one tag.

[deckar01]

@dklotz Good catch. It might easiest to land external docs for tags separately. The templates for operations and signatures can simply be dropped in, but tags might require some UI negation since horizontal real estate is limited.

[obfischer]

+1

[manoharreddyporeddy]

It's perfectly working for me, after a bit of struggle:

1. I took the latest code from github like this:

   git clone https://github.com/swagger-api/swagger-ui.git

2. The JSON is like this:
   {
   'paths': {
   '/pet/addPet': {
   'post': {
   externalDocs: {
   description: 'External documentation: ',
   url: 'https://cawiki.ca.com/display/SFDC/Get+Pending+Cart+Count'
   }}}}}

3. there was a cache problem, so I had to clear Chrome Browser cache many times, to render properly

Hope that will help someone.

[leofoto]

But i think the OP is looking for a way to drive it from the code so the generated swagger-ui.html has the external docs link. I am using springfox api with swagger 2 annotations in a spring boot project and still have this problem. (generated swagger-ui does not include the externalDocs tag

If i take that swagger.json from the ui and put it in the editor.swagger.io and manually edit to insert the externalDocs tag then the link does get rendered on the right side.

I need a way so that i can drive it from my code (with @externalDocs annotation)
any help/advice would be appreciated.

`@RequestMapping(value ="/employees", method = RequestMethod.GET, produces = "application/json")

@ApiOperation(value = "Returns the list of employees matching the search criteria (based on employeeId) " ,response = Employee.class, responseContainer = "List" )

@ExternalDocs(value="ABC API Documentation", url="http://abc.com/docs/DOC-12345")
@ResponseBody
@ApiResponses(value = {
        @ApiResponse(code = 200, message = "Json containing employeeDetails"),
        @ApiResponse(code = 204, message = "No content"),
        @ApiResponse(code = 500, message = "Internal Server Error")})
public List<Person> myMethodName(
        @ApiParam(value = "employeeId:  employee number(digit)", required = true)
        @RequestParam(required = false, defaultValue = "") String employeeId,
        @ApiParam(value = "domain:  domain in which to search the employee (String)" , allowableValues = "aDomain,bDomain,cDomain")
        @RequestParam(required = false, defaultValue = "") String domain) {
    ValidationUtils.validateEmployeeId(employeeId);
    ValidationUtils.validateDomainName(domain);
    return ds.searchByEmplNum(employeeId, domain);
}`

[rhycce]

Its been a while. I'm trying to use this feature. Anyone knows whether this has been resolved. I also want to be able to read external resources from my code for the documentation

[manoharreddyporeddy]

https://github.com/swagger-api/swagger-ui/issues/1614#issuecomment-300080507
Above, worked for me.

[rhycce]

Thanks, but that is manually editing the json file. I want to generate it dynamically from my code. Like here[] [this comment)](https://github.com/swagger-api/swagger-ui/issues/1614#issuecomment-317141072)

[manoharreddyporeddy]

I did automate via external files.
There was a blank template JSON file.
We had test cases per environment (dev, qa & prod) written in various files.
The test case files were read, and written to a copy of the template JSON file, one per environment, they also included different external links, etc.
This way, we had different JSONs with test data included p4er 200, 400 & 500, with various external links, and the swagger UI was per environment.
This all work done, once I did the shared link.
Using Node.js, It took about 3 days of automation.
Hope that helps, if you need more information feel free to ask.

[rhycce]

@manoharreddyporeddy I'm using Java but if you don't mind giving an outline of how you implemented this, I will try to implement it in java.

Currently,my main api calls display perfectly. The issue I'm running into is my data structures are defined by another service. So I have to get the json files which define the datastructure and inject it into the swagger.json file when it is queried.

[manoharreddyporeddy]

Right, that's exactly what I did, injecting into Swagger, the inputs for apis (test cases), and static ouput examples, and anyway it is real-time input, and output will work, we also had authorization working correctly.

So, I can help.

(since I cannot share a proprietary code)

However you need to ask a specific question each time for me to help.
for example, how can I insert a test case (data structure u say)? And, if you need to give your sample data structure, then possibly i will change my names to your yours.

[HolisticDeveloper]

Should Swagger UI be rendering external docs for definitions? I'm currently not seeing it.

[manoharreddyporeddy]

As I recall, I had only 1 external docs, it displayed the web link to an external documentation.

[webron]

Closing this ticket as consolidating it with #1526 #1545 where we'll address all externalDocs rendering.