在前后联调时，一个高质量的接口文档工具是必不可少的。否则就会出现前后台人员不停的来回沟通的现象，浪费大量的时间。在大多数企业的接口文档使用的都是swaager，可能唯一的缺陷就是ui样式不是特别给力。但是有大量的增强性工具可以使用，如yapi，其中支持swagger导出文件的展示。
如果选择其他接口文档工具，可能对比swagger有缺失。请谨慎选择。
博主在公司规定定义时，规定入参值与返回值均为实体类，不允许使用其他基本类型的封装类型。以下使用均在此前提。这里就面临这get请求的问题，如果有兴趣可以接续往下看。
1.整合springboot
1.pom文件新增
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.2.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.2.2</version> </dependency>
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.修改接口
1.入参为String出参为List
此种方式在博主公司不允许出现。
/** * 通过参数查询(多个入参) * * @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<DemoVO> 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格式。
2.入参为实体，出参为list
1.post方式
@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<DemoVO> selectDemoByVo(@RequestBody @ApiParam(name = "用户对象", value = "传入json格式", required = true) DemoVO demoVO) { return demoService.selectDemoVO(demoVO); }
2.get方式
@Log(operationName = "机构部门-查询工作组用户") @GetMapping("/selectWorkSysUser") @ApiOperation(value = "通过实体查询用户", notes = "通过实体查询用户") public Result<List<SysUserVO>> selectWorkSysUser(@ApiParam(name = "入参对象", value = "实体", required = false) SysUserVO sysSysUserVO) throws TemplateException { }
以上是效果，同时respones class和parameters都可以选择样式。
3.入参为List，出参为List
/** * 通过List查询 * * @param demoVO * @return */ @RequestMapping(value = "/selectDemoByList", method = RequestMethod.POST) @ApiOperation(value = "查询城市信息", notes = "根据入参查询城市demo") @ApiImplicitParam(name = "demoVO", value = "入参为List", required = false, dataType = "List<DemoVO>") public List<DemoVO> selectDemoByList(@RequestBody List<DemoVO> demoVO) { return demoService.selectDemoVO(demoVO.get(0)); }
以上是效果，同以上相同
3.常用注解含义
controller类使用 @Api：修饰整个类，描述Controller的作用 @ApiOperation：描述一个类的一个方法，或者说一个接口 @ApiImplicitParams：多个请求参数(一个@ApiImplicitParams包括多个 @ApiImplicitParam) @ApiImplicitParam：一个请求参数 @ApiResponses：HTTP响应整体描述(一个@ApiResponses包括多个@ApiResponse) @ApiResponse：HTTP响应其中1个描述 @ApiIgnore：使用该注解忽略这个API @ApiError ：发生错误返回的信息 @ApiParam：单个参数描述 实体类pojo使用 @ApiModel：用对象来接收参数(pojo类使用) @ApiProperty：用对象接收参数时，描述对象的一个字段(pojo类的参数使用)
