swagger2整合并不是那么随便

2024-03-23 17:35:34

在前后联调时，一个高质量的接口文档工具是必不可少的。否则就会出现前后台人员不停的来回沟通的现象，浪费大量的时间。在大多数企业的接口文档使用的都是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));
    }

以上是效果，同以上相同

三常用注解含义

    controller类使用
    @Api：修饰整个类，描述Controller的作用

    @ApiOperation：描述一个类的一个方法，或者说一个接口

    @ApiImplicitParams：多个请求参数(一个@ApiImplicitParams包括多个 
    @ApiImplicitParam)
    @ApiImplicitParam：一个请求参数

    @ApiResponses：HTTP响应整体描述(一个@ApiResponses包括多个@ApiResponse)
    @ApiResponse：HTTP响应其中1个描述

    @ApiIgnore：使用该注解忽略这个API

    @ApiError ：发生错误返回的信息

    @ApiParam：单个参数描述

    实体类pojo使用
    @ApiModel：用对象来接收参数(pojo类使用)
    @ApiProperty：用对象接收参数时，描述对象的一个字段(pojo类的参数使用)

码农公寓