还在手写api接口文档？试试它吧

2021-09-08 希留说

前言

前后端分离开发模式中，api文档是最好的沟通方式。今天就来说一说如何整合Swagger生成一套漂亮、美观、实用的接口文档。
源码传送门：
https://gitee.com/huoqstudy/xiliu-admin.git

一、Swagger介绍

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务，它有着如下的优点：
1. 及时性 (接口变更后，能够及时准确地通知相关前后端开发人员)
2. 规范性 (并且保证接口的规范性，如接口的地址，请求方式，参数及响应格式和错误信息)
3. 一致性 (接口信息一致，不会出现因开发人员拿到的文档版本不一致，而出现分歧)
4. 可测性 (直接在接口文档上进行测试，以方便理解业务)

二、配置Swagger

1. 添加依赖

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

2. 创建Swagger2配置文件

代码如下（示例）：

@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket apiConfig() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 调用apiInfo方法,创建一个ApiInfo实例,里面是展示在文档页面信息内容
                .apiInfo(apiInfo());
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //大标题
                .title("接口文档")
                //详细描述
                .description("接口文档")
                //版本
                .version("1.0")
                //作者
                .contact(new Contact("xiliu", "http://www.xxx.com", "277769738@qq.com"))
                .build();
    }

}

3. 重启服务查看接口

访问路径：
http://localhost:8081/swagger-ui.html ，出现生成的文档页面。但是作为一个有审美追求的人，这ui也太难看了吧，果断放弃，更换成Knife4j

4. 使用Knife4j

Knife4j的前身是swagger-bootstrap-ui，前身swagger-bootstrap-ui是一个纯swagger-ui的ui皮肤项目。但是随着项目的发展,面对越来越多的个性化需求，不得不编写后端JAVA代码以满足新的需求，因此，项目正式更名为knife4j,取名knife4j是希望它能像一把匕首一样小巧、轻量，并且功能强悍，更名也是希望把她做成一个为Swagger接口文档服务的通用性解决方案，不仅仅只是专注于前端Ui前端。

4.1 添加依赖

需要删除原来引用的swagger依赖

<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>knife4j-spring-boot-starter</artifactId>
	<version>2.0.7</version>
</dependency>

4.2 修改配置类

@Configuration
@EnableSwagger2WebMvc
public class Swagger2Config {

    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("接口文档")
                        .description("# 接口文档")
                        .termsOfServiceUrl("http://www.xx.com/")
                        .contact("277769738@qq.com")
                        .version("1.0")
                        .build())
                //分组名称
                .groupName("2.X版本")
                .select()
                //这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.java.xiliu"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

    /*@Bean
    public Docket apiConfig() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 调用apiInfo方法,创建一个ApiInfo实例,里面是展示在文档页面信息内容
                .apiInfo(apiInfo());
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //大标题
                .title("接口文档")
                //详细描述
                .description("接口文档")
                //版本
                .version("1.0")
                //作者
                .contact(new Contact("xiliu", "http://www.xxx.com", "277769738@qq.com"))
                .build();

    }*/

}

4.3 重启服务查看接口

访问地址：
http://localhost:8081/doc.html，这个ui界面看起来就更美观，更符合国人的使用习惯。

5. 定义接口说明和参数说明

定义在类上：@Api

定义在方法上：@ApiOperation

定义在参数上：@ApiParam

@Api(tags = "用户管理")
@RestController
@RequestMApping("/ucenter/member")
public class MemberController {

    @Autowired
    private MemberService memberService;

    @ApiOperation(value = "所有用户列表")
    @GetMapping(value = "/getAll")
    public List<Member> list(){
        return memberService.list(null);
    }

    @ApiOperation(value = "根据id删除用户")
    @PostMapping(value = "del/{memberId}")
    public boolean deleteById(
            @ApiParam(name = "memberId", value = "用户ID", required = true)
            @PathVariable Long memberId){
        return memberService.removeById(memberId);
    }

    @ApiOperation(value = "保存用户")
    @PostMapping(value = "save")
    public boolean save(
            @ApiParam(name = "member", value = "用户对象json", required = true)
            @RequestBody Member member){
        if (null == member.getMemberId()) {
            return memberService.save(member);
        }
        return memberService.updateById(member);
    }

}

总结

感谢大家的阅读，以上就是今天要讲的内容，本文简单介绍了如何整合Swagger生成api接口文档，虽然很多人喷Swagger，不好用，基于注解，代码入侵很强，等等很多原因。但总体来看，swagger发展至今，包括在各个语言，NodeJs、.NET、java、php等等，它可以说是一个有些接口规范的东西，从开始，到一步步规范，其实是一个很艰难的过程，任何事物，都不是尽善尽美的，swagger也是一样，至少它给这么多语言提供了一种文档生成的解决方案，其价值就远超它本身的缺点。

最后弱弱地问一句，你们的项目用swagger了吗？