swagger2-接口文檔

在使用spring boot進行開發接口時，很好用的就是swagger2接口文檔，自動生成文檔后還能進行測試。spring boot項目集成swagger2就比較容易，但是我在spring mvc的項目中集成swagger2的時候遇到了不少問題，現記錄下，方便以后工作中使用。

0.Spring MVC配置文件中的配置

 

1.maven依賴

 

 

 

2.Swagger配置文件

/*
 * Restful API 訪問路徑:
 * http://IP:port/{context-path}/swagger-ui.html
 * eg:http://localhost:8080/jd-config-web/swagger-ui.html
 */
@EnableWebMvc
@EnableSwagger2
@ComponentScan(basePackages = {"com.thinkgem.jeesite.modules.rmi.web"})
@Configuration
public class RestApiConfig extends WebMvcConfigurationSupport {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.thinkgem.jeesite.modules.rmi.web"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("售電平台接入數據 APIs")
                .termsOfServiceUrl("http://blog.csdn.net/he90227")
                .contact("售電PC")
                .version("1.1")
                .build();
    }
}

 

 

3.Controller中使用注解添加API文檔

 

/**
 *
 * Created by kwt on 2017/8/23.
 */
@Controller
@RequestMapping("${adminPath}/rmi/test/tools")
@Api( value = "設備管理測試", description = "設備管理-測試")
public class TestAmmeterToolsController {
    @Autowired
    private AmmeterToolsUtil ammeterToolsUtil;

    /**
     * 用戶登錄
     * @return
     */
    @ApiOperation(value="用戶登錄接口",notes="用戶登錄接口" ,httpMethod = "POST")
    @RequestMapping(value = "/login", method = RequestMethod.POST)
    @ResponseBody
    public Object login() {
        LoginReq loginReq = new LoginReq();
        loginReq.setUserName("");
        loginReq.setPassword("");
        loginReq.setTypeName("");
        LoginResp login = ammeterToolsUtil.login(loginReq);
        return login;
    }

    /**
     * 用戶下網關查詢
     * @return
     */
    @ApiOperation(value="用戶網關查詢",notes="用戶網關查詢" ,httpMethod = "POST")
    @RequestMapping(value = "/queryGateWay", method = RequestMethod.POST)
    @ResponseBody
    public Object queryGateWay() {
        QueryGatewayResp queryGatewayResp = ammeterToolsUtil.queryGateway();
        return queryGatewayResp;
    }

    /**
     * 網關注冊
     * @return
     */
    @ApiOperation(value="網關注冊",notes="網關注冊" ,httpMethod = "POST")
    @RequestMapping(value = "/registGateway", method = RequestMethod.POST)
    @ResponseBody
    public Object registGateway() {
        RegistGatewayReq registGatewayReq = new RegistGatewayReq();
        registGatewayReq.setGatewayId((long)0);//網關id
        registGatewayReq.setAddress("sjz");//網關安裝地址
        registGatewayReq.setGatewayName("test001");
        registGatewayReq.setTime("2018-08-08");
        RegistGatewayResp regist = ammeterToolsUtil.registGateway(registGatewayReq);
        return regist;
    }

    /**
     * 網關修改
     * @return
     */
    @ApiOperation(value="網關修改",notes="網關修改" ,httpMethod = "POST")
    @RequestMapping(value = "/POSTWayEdit", method = RequestMethod.POST)
    @ResponseBody
    public Object getWayEdit() {
        RegistGatewayReq registGatewayReq = new RegistGatewayReq();
        registGatewayReq.setGatewayId((long)527);//網關id
        registGatewayReq.setAddress("sjz888");//網關安裝地址
        registGatewayReq.setGatewayName("test888");
        registGatewayReq.setTime("2018-08-08");
        RegistGatewayResp regist = ammeterToolsUtil.registGateway(registGatewayReq);
        return regist;
    }


    /**
     * 刪除網關
     * @return
     */
    @ApiOperation(value="刪除網關",notes="刪除網關" ,httpMethod = "POST")
    @RequestMapping(value = "/deleteGateway", method = RequestMethod.POST)
    @ResponseBody
    public Object deleteGateway() {
        DeleteGatewayReq deleteGatewayReq = new DeleteGatewayReq();
        List<Long> gatewayIdList = new ArrayList<>();
        gatewayIdList.add((long)535);
        deleteGatewayReq.setGatewayIdList(gatewayIdList);
        DeleteGatewayResp deleteGatewayResp = ammeterToolsUtil.deleteGateway(deleteGatewayReq);
        return deleteGatewayResp;
    }


    /**
     * 查詢網關下設備
     * @return
     */
    @ApiOperation(value="查詢網關下設備",notes="查詢網關下設備" ,httpMethod = "POST")
    @RequestMapping(value = "/queryDevice", method = RequestMethod.POST)
    @ResponseBody
    public Object queryDevice() {
        QueryDeviceReq queryDeviceReq = new QueryDeviceReq();
        queryDeviceReq.setGatewayId((long)527);
        QueryDeviceResp queryDeviceResp = ammeterToolsUtil.queryDevice(queryDeviceReq);
        return queryDeviceResp;
    }


    /**
     * 網關下添加設備
     * @return
     */
    @ApiOperation(value="網關下添加設備",notes="網關下添加設備" ,httpMethod = "POST")
    @RequestMapping(value = "/addDevice", method = RequestMethod.POST)
    @ResponseBody
    public Object addDevice() {
        AddDeviceReq addDeviceReq = new AddDeviceReq();
        addDeviceReq.setDeviceNo("設備編號——001");
        addDeviceReq.setDeviceName("設備名稱");
        //addDeviceReq.setDeviceLabelInfoList();
        addDeviceReq.setGatewayId((long)534);
        addDeviceReq.setDeviceId((long)0);
       /* addDeviceReq.setDeviceTypeId();
        addDeviceReq.setOrderInGateway();
        addDeviceReq.setProtocolInfoList();
        addDeviceReq.setProtocolTypeId();
        addDeviceReq.setStartAddr();
        addDeviceReq.setTempletTypeId();*/

        AddDeviceResp addDeviceResp = ammeterToolsUtil.addDevice(addDeviceReq);
        return addDeviceResp;
    }
}

 

 

 

 

 

4.效果展示

訪問路徑：http: //IP:port//swagger-ui.html

參考：http://blog.csdn.net/phantomes/article/details/52334591

注：我在spring mvc中配置時沒有做第0步驟，但是能夠生成文檔，具體的原因還有待研究；

 

 

接下來就是對UI界面的優化，目前生成的界面不方便看，還比較丑，所以就集成了一個UI項目。

 

訪問路徑：http://localhost:8080/doc.html

 

參考：https://git.oschina.net/xiaoym/swagger-bootstrap-ui

注：原作者還沒有將最新版本發布到maven中央倉庫，所以無法使用，本人使用的是舊版本。依賴如下：

<dependency>
 <groupId>com.drore.cloud</groupId>
 <artifactId>swagger-bootstrap-ui</artifactId>
 <version>1.4</version>
</dependency>

使用該依賴替換集成swagger2時使用的UI依賴即可。

當時按照spring boot項目集成的插件進行設置，但是在接口名稱上沒有生成，還有待研究，先寫下一個不太完整的日志。