SprongBoot+MyBatis+Redis+MySql 搭建Web开发项目系列 整合swagger2

1. Swagger 简介

Swagger是一款Restful接口的文档在线自动生成和功能测试功能软件。
Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化Restful风格的Web服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

2. Swagger 依赖

        <!--swagger2依赖-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

3. Swagger 配置文件

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    //是否开启swagger，正式环境一般是需要关闭的
    @Value("${swagger.enabled}")
    private boolean enableSwagger;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //是否开启 (true 开启  false隐藏。生产环境建议隐藏)
                .enable(enableSwagger)
                .select()
                //扫描的路径包,设置basePackage会将包下的所有被@Api标记类的所有方法作为api
                .apis(RequestHandlerSelectors.basePackage("com.springboot.chapter04.controller"))
                //指定路径处理PathSelectors.any()代表所有的路径
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //设置文档标题(API名称)
                .title("SpringBoot中使用Swagger2构建RESTful接口")
                //文档描述
                .description("接口说明")
                //版本号
                .version("1.0.0")
                .build();
    }
}

4. 编写测试控制器

@RestController
@RequestMapping("user")
@Api(value = "测试接口", tags = "UserController", description = "测试接口相关")
public class UserController {
    @Autowired
    private IUserService userService;


    @RequestMapping(value = "/save", method = RequestMethod.POST)
    //@ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "User")
    @ApiOperation(value = "创建用户", notes = "创建用户")
    public Map<String, Object> saveUser(@ApiParam(required = true, name = "user", value = "用户实体user") @RequestBody User user) {
        Map<String, Object> ret = new HashMap<>();
        try {
            if (null == user) {
                ret.put( "msg", "参数不能为空" );
                return ret;
            }
            boolean row = userService.saveOrUpdate( user );
            if (row) {
                ret.put( "msg", "添加成功" );
            } else {
                ret.put( "msg", "添加失败" );
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
        return ret;
    }

    /**
     * @param id
     * @return
     */
    @RequestMapping(value = "/get/{id}", method = RequestMethod.GET, produces = "application/json")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "query")
    @ApiOperation(value = "获取用户详细信息", notes = "根据id来获取用户详细信息")
    public Map<String, Object> getUser(@RequestParam Long id) {
        Map<String, Object> ret = new HashMap<>();
        try {
            User user = userService.getById( id );
            if (null == user) {
                ret.put( "msg", "用户ID：" + id + "，未找到数据" );
            } else {
                ret.put( "msg", "获取成功" );
                ret.put( "data", user );
            }

        } catch (Exception e) {
            e.printStackTrace();
        }
        return ret;
    }

    /**
     * paramType:指定参数放在哪个地方
     * path:（用于restful接口）-->请求参数的获取：@PathVariable
     *
     * @param id
     * @return
     */
    @RequestMapping(value = "/delete/{id}", method = RequestMethod.DELETE)
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path")
    @ApiOperation(value = "删除用户", notes = "删除用户")
    public Map<String, Object> deleteUser(@PathVariable Long id) {
        Map<String, Object> ret = new HashMap<>();
        if (null == id) {
            ret.put( "msg", "参数不能为空" );
            return ret;
        }
        boolean row = userService.removeById( id );
        if (row ) {
            ret.put( "msg", "删除成功" );
        } else {
            ret.put( "msg", "删除失败" );
        }
        return ret;
    }

    /**
     * ApiIgnore 使用该注解忽略这个API，不会生成接口文档。可注解在类和方法上
     *
     * @return
     */
    @ApiIgnore
    @RequestMapping(value = "/getAll", method = RequestMethod.GET, produces = "application/json")
    @ApiOperation(value = "获取用户列表", notes = "获取用户列表")
    public Map<String, Object> getAll() {
        Map<String, Object> ret = new HashMap<>();
        ret.put( "msg", "获取成功" );
        return ret;
    }
}

4. Swagger页面访问
   运行项目，输入 http://localhost:端口/swagger-ui.html 访问Swagger页面
   

5. 项目完整目录
   

6. 后记
   (1) 遇到系统报错，但不影响使用，报错内容如下

2021-03-24 08:47:19.353  WARN 3176 --- [nio-8033-exec-6] i.s.m.p.AbstractSerializableParameter    : Illegal DefaultValue  for parameter type integer

java.lang.NumberFormatException: For input string: ""

有兴趣的可以参考 ：https://blog.csdn.net/weixin_42835717/article/details/88051334
博文解决。

给自己，点点滴滴，持续进步。。。。