Overwriting Swagger 2.0 document fields
Use a swaggerDefinition
attribute in a server.xml
file to overwrite some fields in the Swagger 2.0 documents that are provided by the
/docs
and /explorer
endpoints.
Before you begin
You must first add the apiDiscovery-1.0
feature to your
server.xml file and then expose the Swagger 2.0 documentation in Liberty REST endpoints. Complete steps 1 and 2 of
the procedure in Discovering REST API documentation on a Liberty server.
Procedure
-
Create a
swaggerDefinition
snippet to specify a JSON or YAML Swagger snippet that contains fields to overwrite. You can overwrite theinfo
,schemes
,consumes
,produces
, andexternalDocs
fields.For example, the following
swaggerDefinition
snippet changesdescription
,title
, and otherinfo
fields in the /explorer HTML pages.{ "swagger":"2.0", "info":{ "description":"My description", "version":"1.0.0", "title":"My title", "x-ibm-css":"${server.config.dir}/css/acme-banner.css", "termsOfService":"http://swagger.io/terms/", "contact":{ "email":"apiteam@swagger.io" }, "license":{ "name":"Apache 2.0", "url":"http://www.apache.org/licenses/LICENSE-2.0.html" } } }
In addition to the
title
and thedescription
values, you can customize the banner and the logo HTML elements in the /explorer HTML pages. Inside theinfo
field of theswaggerDefinition
snippet, you can specify anx-ibm-css
field to point to a location of a CSS file that overrides the banner and logo portion. This CSS file has the following format requirements:- The CSS file must specify a
.swagger-section #header
CSS element. - Any new logos must use the
images/custom-logo.png
format, where custom-logo is the name of the image file. Make the logo file path relative to the CSS file. - The CSS file must reference the custom logo image with the
background-image
property set to theurl(images/custom-logo.png)
value. - The logo file must be in the PNG format.
An example of an overriding CSS file follows:
.swagger-section #header { background-image: url(images/custom-logo.png); background-repeat: no-repeat; background-color: lightslategray; background-position-x: 28px; padding-top: 20px; padding-right: 0px; padding-bottom: 20px; padding-left: 5px; height: 75px; }
- The CSS file must specify a
-
Add a
swaggerDefinition
attribute to your server.xml file.The
swaggerDefinition
attribute value can be one of the following values:- Path of a local file that ends with the .json or .yaml
file extension. This path can include Liberty variables that are associated with runtime
directories; for example:
<apiDiscovery swaggerDefinition="${server.config.dir}/custom/swaggerDef.yaml" />
- Absolute URL of a Swagger snippet that starts with http or
https; for
example:
<apiDiscovery swaggerDefinition="http://mycompany.com/api/swaggerDef.json" />
- Context root of an application that is deployed on the server. The context root starts with a
forward slash (
/
); for example:<apiDiscovery swaggerDefinition="/myApplication" />
To enhance the user experience of a Liberty server that contains one deployed web application, the Swagger document of the web application is used as a
swaggerDefinition
snippet. All the fields from the application are overridden in a Swagger document that is provided by the /docs endpoints even though aswaggerDefinition
attribute is not defined in the server.xml. When a second web application is deployed on a server, all the fields that are affected by the single application optimization revert to their default values. - Path of a local file that ends with the .json or .yaml
file extension. This path can include Liberty variables that are associated with runtime
directories; for example: