springboot集成swagger2生产API文档

springboot项目中，前后端分离开发，前端页面要调用后端api处理业务就需要知道api接口的详细说明，包括调用路径、调用方式、入参、出参等相关要素。在早些年的时候，前后端人员都是通过编写word接口文档方式进行沟通，工作量非常大，沟通效率也不高。在swigger出现后，开发人员彻底从编写word接口文档中解放出来，把精力放在具体的业务实现上。
swigger是一款能够自动生成api接口文档的框架，我们只需要根据swigger提供的语言规范在API接口处添加对应的描述，它就能自动生成接口文档，并能够在线查看，大大缩减了前后端开发人员的沟通成本。

1.添加swagger依赖

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.1</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency>

2.配置swagger

@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("xxx林业平台")
                .description("xxx林业平台后台api接口文档")
                .termsOfServiceUrl("127.0.0.1:9000") //根据本机端口配置
                .version("1.0")
                .build();
    }

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.cc.app")) //api包路径
                .paths(PathSelectors.regex("/api/.*")) //api的path
                .build();
    }
}

3.使用swagger注解
通过swagger提供的注解对api接口进行描述，swagger根据描述生成api接口文档。
常用的注解如下：
@Api(value = "/api/jc_sp_line", description = "样线监测数据") 用于类描述
@ApiOperation(value = "根据ID查询信息",notes = "根据ID查询信息") 用于方法描述
@ApiImplicitParam(name = "params", value = "UID 如：{id:'aa'}" ) 用于参数字段描述
@ApiImplicitParams({
@ApiImplicitParam(name = "name", value = "姓名"),
@ApiImplicitParam(name = "age", value = "年龄")
}) 用于多个参数字段描述

具体代码使用如下：

/**
 * 样线监测数据模块控制层
 * creater shah on 2020/02/05
 **/
@Api(value = "/api/jc_sp_line", description = "样线监测数据")
@RestController
@RequestMapping("/api/jc_sp_line")
public class JcSPLineController extends BaseController{
    private static Logger logger = LoggerFactory.getLogger(JcSPLineController.class);

    @Autowired
    public JcSPLineService service;


    /**
     * 根据ID查询信息
     * @param uid
     * @return
     */
    @ApiOperation(value = "根据ID查询信息",notes = "根据ID查询信息")
    @RequestMapping(value = "/findAllByID", method = RequestMethod.GET)
    public Object findAllByID(String uid){
        JcSPLine bean=service.findInfoByID(uid);
        return RtnData.ok(bean);
    }

    @ApiOperation(value = "单笔删除样线监测数据",notes = "单笔删除样线监测数据")
    @ApiImplicitParam(name = "params", value = "UID 如：{id:'aa'}" )
    @RequestMapping(value = "/delete",method = RequestMethod.POST)
    public RtnData delete(@RequestBody Map params){
        service.delete((String) params.get("id"));
        return RtnData.ok("success");
    }

4.查看swagger生成的接口文档
项目启动后，访问地址：http://localhost:9000/swagger-ui.html，可以看到API文档界面：

image.png

点开一个controller条目，可以看到API接口列表：

image.png

点开一个接口方法，可以看到接口参数详情：

image.png

是不是很详细，是不是很方便！！！

*妈妈以后再也不用担心我跟前端妹子吵架了，好开心！