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项目集成的插件进行设置，但是在接口名称上没有生成，还有待研究，先写下一个不太完整的日志。