企业级springboot落地：swagger2整合并不是那么随便

在前后联调时，一个高质量的接口文档工具是必不可少的。否则就会出现前后台人员不停的来回沟通的现象，浪费大量的时间。在大多数企业的接口文档使用的都是swaager，可能唯一的缺陷就是ui样式不是特别给力。但是有大量的增强性工具可以使用，如yapi，其中支持swagger导出文件的展示。

如果选择其他接口文档工具，可能对比swagger有缺失。请谨慎选择。

博主在公司规定定义时，规定入参值与返回值均为实体类，不允许使用其他基本类型的封装类型。以下使用均在此前提。这里就面临这get请求的问题，如果有兴趣可以接续往下看。

1.整合springboot

1.pom文件新增

io.springfox springfox-swagger2 2.2.2 io.springfox springfox-swagger-ui 2.2.2

2.新增config文件

@Configuration public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() //controller包 .apis(RequestHandlerSelectors.basePackage("com.airboot.bootdemo.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("文档标题") .description("文档描述") .termsOfServiceUrl("http://blog.csdn.net/saytime") .version("1.0") .build(); } }

3.application中添加注解

这里需要添加增加@EnableSwagger2注解。

@SpringBootApplication @EnableSwagger2 public class BootdemoApplication { public static void main(String[] args) { SpringApplication.run(BootdemoApplication.class, args); } }

以上步骤完成后，就可以使用了，可以访问http://localhost:[端口]/swagger-ui.html#/

附上文件结构

2.接口使用swagger2

1.修改实体类

如果需要返回的实体类带中文名称需要以下配置。

@ApiModel(value="DemoVO",description="对象") public class DemoVO { private static final long serialVersionUID = -1L; /** * 城市编号 */ @ApiModelProperty(value="id",name="id") private Long id; /** * 省份编号 */ @ApiModelProperty(value="省份编号",name="省份编号") private Long provinceId; /** * 城市名称 */ @ApiModelProperty(value="城市名称",name="城市名称") private String cityName; /** * 描述 */ @ApiModelProperty(value="描述",name="描述") private String description;

2.修改接口

此种方式在博主公司不允许出现。

/** * 通过参数查询(多个入参) * * @return */ @RequestMapping(value = "/selectDemoByParas", method = RequestMethod.GET) @ApiOperation(value = "查询城市信息", notes = "根据入参查询城市demo(入参为Long)")//notes 描述 @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "主键", required = true, dataType = "Long", paramType = "path"), //required 是否必填，dataType入参类型 @ApiImplicitParam(name = "provinceId", value = "省份id", required = false, dataType = "Long", paramType = "path") }) @ApiResponses(value = { @ApiResponse(code = 200, message = "成功"), @ApiResponse(code = 400, message = "参数格式错误"), @ApiResponse(code = 401, message = "登录错误"), @ApiResponse(code = 404, message = "未找到地址"), @ApiResponse(code = 500, message = "服务器错误")} ) public List selectDemoByParas(@RequestParam("id") Long id, @RequestParam("provinceId") Long provinceId) { DemoVO inputVO = new DemoVO(); inputVO.setId(id); return demoService.selectDemoVO(inputVO); }

以上是文档效果，同时respones class下的model和model schema可以更换返回对象样式。

可以通过try it out测试接口 同时可以切换显示注释的中文名称和json格式。

@RequestMapping(value = "/selectDemoByVo", method = RequestMethod.POST) @ApiOperation(value = "查询城市信息", notes = "根据入参查询城市demo") //入参是pojo有三种方法 //1.@ApiParam //2.@ApiImplicitParam(name = "demoVO", value = "入参为VO", required = false, dataType = "DemoVO") //3.@ApiImplicitParams({ //@ApiImplicitParam(name = "id", value = "主键", required = true, dataType = "Long", paramType = "path"), //@ApiImplicitParam(name = "provinceId", value = "省份id", required = false, dataType = "Long", paramType = "path") //}) //!!!!但是建议使用@ApiParam 这样可以显示出入参格式和中文名称 如例 public List selectDemoByVo(@RequestBody @ApiParam(name = "用户对象", value = "传入json格式", required = true) DemoVO demoVO) { return demoService.selectDemoVO(demoVO); }

@Log(operationName = "机构部门-查询工作组用户") @GetMapping("/selectWorkSysUser") @ApiOperation(value = "通过实体查询用户", notes = "通过实体查询用户") public Result> selectWorkSysUser(@ApiParam(name = "入参对象", value = "实体", required = false) SysUserVO sysSysUserVO) throws TemplateException { }

以上是效果，同时respones class和parameters都可以选择样式。

/** * 通过List查询 * * @param demoVO * @return */ @RequestMapping(value = "/selectDemoByList", method = RequestMethod.POST) @ApiOperation(value = "查询城市信息", notes = "根据入参查询城市demo") @ApiImplicitParam(name = "demoVO", value = "入参为List", required = false, dataType = "List") public List selectDemoByList(@RequestBody List demoVO) { return demoService.selectDemoVO(demoVO.get(0)); }

以上是效果，同以上相同

三 常用注解含义

controller类使用 @Api：修饰整个类，描述Controller的作用 @ApiOperation：描述一个类的一个方法，或者说一个接口 @ApiImplicitParams：多个请求参数(一个@ApiImplicitParams包括多个 @ApiImplicitParam) @ApiImplicitParam：一个请求参数 @ApiResponses：HTTP响应整体描述(一个@ApiResponses包括多个@ApiResponse) @ApiResponse：HTTP响应其中1个描述 @ApiIgnore：使用该注解忽略这个API @ApiError ：发生错误返回的信息 @ApiParam：单个参数描述 实体类pojo使用 @ApiModel：用对象来接收参数(pojo类使用) @ApiProperty：用对象接收参数时，描述对象的一个字段(pojo类的参数使用)

Spring Boot

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。