SpringBoot整合Swagger实现接口文档

╰+攻爆jí腚メ 2021-07-25 01:05 559阅读 0赞

在项目开发中，一般都是前后端分离开发的，需要由前后端工程师共同定义接口，编写接口文档，之后大家都根据这个接口文档进行开发、维护。

为了便于编写和维护稳定，可以使用Swagger来编写API接口文档，以提升团队的沟通效率。

**【示例】**SpringBoot整合Swagger实现接口文档。

# 1、配置Swagger #

**（1）添加Swagger依赖。**

在pop.xml文件中加入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>

**（2）创建Swagger配置类。**

创建Swagger配置类，完成相关配置项。

package com.pjb.config;
    
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    /**
     * Swagger 配置类
     * @author pan_junbiao
     **/
    @Configuration
    @EnableSwagger2
    public class SwaggerConfig
    {
        /**
         * 创建API应用
         */
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.pjb.controller"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        /**
         * 创建该API的基本信息（这些基本信息会展现在文档页面中）
         * 访问地址：http://项目实际地址/swagger-ui.html
         */
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title(" RESTful APIs")
                    .description("RESTful APIs")
                    .termsOfServiceUrl("http://localhost:8080/")
                    .contact("long")
                    .version("1.0")
                    .build();
        }
    }

# 2、编写接口文档 #

在完成上述配置后，即生成了文档，但是这样生成的文档主要针对请求本身，而描述自动根据方法等命名产生，对用户并不友好。所以，通常需要自己增加一些说明以丰富文档内容。可以通过以下注解来增加说明。

@Api：描述类/接口的主要用途，用在类（控制器类）上。

@ApiOperation：描述方法用途，给API增加说明，用在方法上。

@ApiImplicitParam：描述方法的参数，给参数增加说明。

@ApiImplicitParams：描述方法的参数( Multi-Params)，给参数增加说明。

@ApiIgnore：忽略某类/方法/参数的文档。

具体使用方法见如下：

/**
     * 删除用户信息
     * @author pan_junbiao
     */
    @ApiOperation(value="删除用户信息",notes="根据URL的id来指定删除的用户信息")
    @ApiImplicitParam(name="id",value = "用户ID", required = true, dataType = "int")
    @RequestMapping(value = "/{id}", method = RequestMethod.DELETE)
    public ApiResultModel deleteUserInfo(@PathVariable("id")int userId)
    {
        //删除用户信息
        userDao.deleteById(userId);
    
        //返回结果
        ApiResultModel apiResultModel = new ApiResultModel();
        apiResultModel.statusCode = ApiStatusCode.SUCCESS.getCode();
        apiResultModel.message = ApiStatusCode.SUCCESS.getDescription();
        apiResultModel.data = true;
        return apiResultModel;
    }

完整的实例代码：

package com.pjb.controller;
    
    import com.pjb.dao.UserDao;
    import com.pjb.entity.UserInfo;
    import com.pjb.model.ApiResultModel;
    import com.pjb.model.ApiStatusCode;
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiImplicitParam;
    import io.swagger.annotations.ApiOperation;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.web.bind.annotation.*;
    
    import java.util.List;
    
    /**
     * 用户信息控制器
     * @author pan_junbiao
     **/
    @Api(description = "用户信息控制器")
    @RestController
    @RequestMapping("user")
    public class UserController
    {
        @Autowired
        private UserDao userDao;
    
        /**
         * 获取用户列表
         */
        @ApiOperation(value="获取用户列表",notes="获取所有用户信息列表")
        @RequestMapping(value = "/", method = RequestMethod.GET)
        public ApiResultModel getUserList()
        {
            //获取用户列表
            List<UserInfo> userInfoList = userDao.findAll();
    
            //返回结果
            ApiResultModel apiResultModel = new ApiResultModel();
            apiResultModel.statusCode = ApiStatusCode.SUCCESS.getCode();
            apiResultModel.message = ApiStatusCode.SUCCESS.getDescription();
            apiResultModel.data = userInfoList;
            return apiResultModel;
        }
    
        /**
         * 获取用户信息
         */
        @ApiOperation(value="获取用户信息",notes="根据URL的id来指定获取的用户信息")
        @ApiImplicitParam(name="id",value = "用户ID", required = true, dataType = "int")
        @RequestMapping(value = "/{id}", method = RequestMethod.GET)
        public ApiResultModel getUserInfo(@PathVariable("id")int userId)
        {
            //根据用户ID，获取用户信息
            UserInfo userInfo = userDao.findById(userId).orElse(null);
    
            //返回结果
            ApiResultModel apiResultModel = new ApiResultModel();
            apiResultModel.statusCode = ApiStatusCode.SUCCESS.getCode();
            apiResultModel.message = ApiStatusCode.SUCCESS.getDescription();
            apiResultModel.data = userInfo;
            return apiResultModel;
        }
    
        /**
         * 新增用户信息
         */
        @ApiOperation(value="新增用户信息")
        @RequestMapping(value = "/", method = RequestMethod.POST)
        public ApiResultModel addUser(@RequestBody UserInfo userInfo)
        {
            //参数验证
            if(userInfo.getUserName()==null || userInfo.getUserName().length()==0)
            {
                //返回参数缺失
                ApiResultModel apiResultModel = new ApiResultModel();
                apiResultModel.statusCode = ApiStatusCode.PARAM_INVALID.getCode();
                apiResultModel.message = ApiStatusCode.PARAM_INVALID.getDescription();
                apiResultModel.data = false;
                return apiResultModel;
            }
    
            //新增用户信息
            userDao.save(userInfo);
    
            //返回结果
            ApiResultModel apiResultModel = new ApiResultModel();
            apiResultModel.statusCode = ApiStatusCode.SUCCESS.getCode();
            apiResultModel.message = ApiStatusCode.SUCCESS.getDescription();
            apiResultModel.data = true;
            return apiResultModel;
        }
    
        /**
         * 修改用户信息
         */
        @ApiOperation(value="修改用户信息",notes="根据URL的id来指定修改的用户信息")
        @ApiImplicitParam(name="id",value = "用户ID", required = true, dataType = "int")
        @RequestMapping(value = "/", method = RequestMethod.PUT)
        public ApiResultModel updateUser(@RequestBody UserInfo userInfo)
        {
            //参数验证
            if(userInfo.getUserId()<=0 || userInfo.getUserName()==null || userInfo.getUserName().length()==0)
            {
                //返回参数缺失
                ApiResultModel apiResultModel = new ApiResultModel();
                apiResultModel.statusCode = ApiStatusCode.PARAM_INVALID.getCode();
                apiResultModel.message = ApiStatusCode.PARAM_INVALID.getDescription();
                apiResultModel.data = false;
                return apiResultModel;
            }
    
            //修改用户信息
            userDao.save(userInfo);
    
            //返回结果
            ApiResultModel apiResultModel = new ApiResultModel();
            apiResultModel.statusCode = ApiStatusCode.SUCCESS.getCode();
            apiResultModel.message = ApiStatusCode.SUCCESS.getDescription();
            apiResultModel.data = true;
            return apiResultModel;
        }
    
        /**
         * 删除用户信息
         */
        @ApiOperation(value="删除用户信息",notes="根据URL的id来指定删除的用户信息")
        @ApiImplicitParam(name="id",value = "用户ID", required = true, dataType = "int")
        @RequestMapping(value = "/{id}", method = RequestMethod.DELETE)
        public ApiResultModel deleteUserInfo(@PathVariable("id")int userId)
        {
            //删除用户信息
            userDao.deleteById(userId);
    
            //返回结果
            ApiResultModel apiResultModel = new ApiResultModel();
            apiResultModel.statusCode = ApiStatusCode.SUCCESS.getCode();
            apiResultModel.message = ApiStatusCode.SUCCESS.getDescription();
            apiResultModel.data = true;
            return apiResultModel;
        }
    }

# 3、运行测试 #

完成上述代码后，启动项目，访问 [http://127.0.0.1:8080/swagger-ui.html][http_127.0.0.1_8080_swagger-ui.html] 就能看到所展示的RESTful API的页面，可以通过单击具体的API测试请求，来查看代码中配置的信息，以及参数的描述信息。

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3Bhbl9qdW5iaWFv_size_16_color_FFFFFF_t_70][]  
![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3Bhbl9qdW5iaWFv_size_16_color_FFFFFF_t_70 1][]

点击测试，获取用户信息，执行结果如下：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3Bhbl9qdW5iaWFv_size_16_color_FFFFFF_t_70 2][]

[http_127.0.0.1_8080_swagger-ui.html]: http://127.0.0.1:8080/swagger-ui.html
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3Bhbl9qdW5iaWFv_size_16_color_FFFFFF_t_70]: /images/20210724/8ce8fb2f08b14864bc71e9b5a7ddf944.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3Bhbl9qdW5iaWFv_size_16_color_FFFFFF_t_70 1]: /images/20210724/70896b5851a94dcdb915a441a3359ab4.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3Bhbl9qdW5iaWFv_size_16_color_FFFFFF_t_70 2]: /images/20210724/52b0d06472ed47108dc9851a4db00cf1.png