Setting the Api Version with Swagger UI

问题:

I have a REST API developed through the use of Jersey and we document the REST API through swagger-ui. Unfortunately, we did not start versioning the API from day 1. We are now trying to add versioning to the API.

The first step I'm taking is I'm trying to update the API version that is displayed by the dynamically generated swagger (html) page. I've traced the call flow all the way to the swagger-ui.js file but I can't figure out how to change the displayed API version at the bottom of the dynamically generated page.

The default that is currently displayed at the bottom is ' API VERSION: 1.0.0 '.

I've read something about a ServiceStack here but unfortunately the code base I'm working on doesn't use anything of the sort.

Could anyone please kindly point me to where/what I would need to change/update in order to update the displayed API version number?

回答1:

You can add a Bootstrap servlet to set parameters for the Swagger config bean as described here -

https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-Jersey-2.X-Project-Setup-1.5

回答2:

API version displayed at the bottom of the Swagger UI is coming from the Swagger document.

Here is an example Swagger document:

{
    "swagger": "2.0",
    "info": {
        "description": "This is a sample server Petstore server.",
        "version": "1.0.0",
        "title": "Swagger Petstore",
    ...

"version": "1.0.0" is the default value but you can change it using the Swagger @Info annotation:

@SwaggerDefinition(
    info = @Info(
        description = "This is a sample server Petstore server.",
        version = "1.0.1",
        title = "Swagger Petstore"

This document can be added to any class scanned during the Swagger auto-configuration process as per the Swagger Wiki page:

The annotation can be on any class scanned during the Swagger auto-configuration process, i.e. it does not have to be on a JAX-RS API class but could just be on a marker/config interface

You can find some samples here: https://github.com/swagger-api/swagger-samples/tree/master/java. Some are using Jersey and setting the API version.

回答3:

It's pretty straight forward -

1. Add a servlet to set the Swagger Bootstrap properties in your deployment descriptior file.
<servlet>
        <servlet-name>SwaggerBootstrap</servlet-name>
        <servlet-class>com.example.util.SwaggerBootstrap</servlet-class>
        <init-param>
            <description>URL Pattern Mapping</description>
            <param-name>paramName</param-name>
            <param-value>uri value</param-value>
        </init-param>
        <load-on-startup>2</load-on-startup>
    </servlet>

2. Create a servlet and set the Bean properties as below --

public void init(ServletConfig servletConfig) 
{
        try {

            // Setting the BeanConfig for start-up page
            BeanConfig bean = new BeanConfig();
            bean.setScan(true);
            bean.setResourcePackage("com.example.util");
            bean.setBasePath("yourBasePath"));  
            bean.setVersion("1.0");
            bean.setTitle("title"));
            bean.setDescription("description");

        } catch (IOException e) {
            e.printStackTrace();
        }
    }