<返回更多

还在手写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

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

 

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界面看起来就更美观,更符合国人的使用习惯。

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

 

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);
    }

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

 

总结

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

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

声明:本站部分内容来自互联网,如有版权侵犯或其他问题请与我们联系,我们将立即删除或处理。
▍相关推荐
更多资讯 >>>