JApiDocs与Swagger对比

最新推荐文章于 2025-06-18 15:27:43 发布

四问四不知

最新推荐文章于 2025-06-18 15:27:43 发布

阅读量1.3k

点赞数 1

CC 4.0 BY-SA版权

分类专栏：笔记

本文链接：https://blog.csdn.net/zkkzpp258/article/details/115718864

笔记专栏收录该内容

63 篇文章

订阅专栏

本文比较了Swagger和新工具JApiDocs在文档自动生成和易用性上的差异，探讨了它们各自的优缺点，以及市场上其他工具如apigcc、knife4j等的简洁性趋势。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

序言

做过Java web开发的小伙伴都用过Swagger，开发过程中的一个小工具，虽然用起来也不麻烦，但是今天看到一篇文章说新的工具能够替代Swagger，那么自己就来实践对比一下到底新工具JApiDocs真的有那么香吗？

Swagger

官方网站：https://swagger.io/

Swagger 是一款RESTFUL接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具。

这里使用的是2.9.2版本。依赖如下，

<!-- swagger -->
<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>

做过开发的小伙伴应该特别熟了，通过@ApiModel+@ApiModelProProperty给对象进行属性注入，在访问控制层通过@Api+@ApiOperation对接口参数进行注入，如果想对swagger的界面做一些配置可以加上下面的代码，

package com.hust.zhang.web.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.format.FormatterRegistry;
import org.springframework.http.converter.HttpMessageConverter;
import org.springframework.validation.MessageCodesResolver;
import org.springframework.validation.Validator;
import org.springframework.web.method.support.HandlerMethodArgumentResolver;
import org.springframework.web.method.support.HandlerMethodReturnValueHandler;
import org.springframework.web.servlet.HandlerExceptionResolver;
import org.springframework.web.servlet.config.annotation.*;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo() {
        // springfox.documentation.service.Contact
        Contact contact = new Contact("zhang", "https://blog.csdn.net/zkkzpp258", "345921046.com");
        return new ApiInfoBuilder()
                .title("test by mr zhang")
                .description("测试swagger")
                .contact(contact)
                .version("1.0.0")
                .build();
    }
}

下面写一个简单的测试接口展示一下使用界面。

JApiDocs

官方网站：https://japidocs.agilestudio.cn/#/

虽然小伙伴们都已经习惯了使用Swagger，不过了解一下新的工具也未尝不可。毕竟听说JApiDocs是一个无需额外注解、开箱即用的SpringBoot接口文档生成工具。

依赖如下，

<dependency>
  <groupId>io.github.yedaxia</groupId>
  <artifactId>japidocs</artifactId>
  <version>1.4.2</version>
</dependency>

在test文件里去写测试文件，记得项目根目录路径一定要设置对。

    @Test
    public void test(){
        DocsConfig config = new DocsConfig();
        //root project path
        config.setProjectPath("/Users/kaizhang/workspace/hust-zhang");
        // project name
        config.setProjectName("test-japi-docs");
        // api version
        config.setApiVersion("V1.0.0");
        // api docs target path
        config.setDocsPath("/Users/kaizhang/workspace/hust-zhang/docs");
        // auto generate
        config.setAutoGenerate(Boolean.TRUE);
        // execute to generate
        Docs.buildHtmlDocs(config);
    }

最后在你设置的DocsPath里生成了html的静态页面，在静态里面可以展示最后的API文档，如下图

总结

有人说swagger对代码入侵太严重，需要写大量的注解去注入信息，较为麻烦。今天新了解到的JApiDocs虽然配置少了一些，但感觉也一般般。于是又查了一下有没有其他的Api文档工具，比如apigcc、knife4j、smart-doc。这种工具本身就是为了减少我们开发人员书写文档的需求，我个人觉得还是越简单越好。至于各个公司如何选型，决定权还是得交给上级（狗头保命）。