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

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 : swag1

What I want to have : swag2

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 ?

About this issue

Original URL
State: closed
Created 9 years ago
Reactions: 6
Comments: 17 (3 by maintainers)

Most upvoted comments

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);
}`

leofoto on Jul 22, 2017

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

There are four objects that allow external documentation:

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:

main (Swagger Object)
operation (Operation Object)
signature (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.

deckar01 on Jun 7, 2016