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.

1. Create a swaggerDefinition snippet to specify a JSON or YAML Swagger snippet that contains fields to overwrite. You can overwrite the info, schemes, consumes, produces, and externalDocs fields.

   For example, the following swaggerDefinition snippet changes description, title, and other info 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 the description values, you can customize the banner and the logo HTML elements in the /explorer HTML pages. Inside the info field of the swaggerDefinition snippet, you can specify an x-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 the url(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;
   }
   

2. 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 a swaggerDefinition 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.