生成接口文档JApiDocs和Swagger对比与实现方法

JApiDocs通过注释实现无侵入式生成接口文档

依赖包

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

注释方法

        1、bean类添加注释 ，注意注释添加到属性后面

public class Student{
    private String username; //用户名
    private String password; //用户密码
    //... 省略构造方法和get/set方法
}

       2、controller添加方法注释，注意注释方式，使用IDEA编辑器 /** + Enter可轻松生成，再添入增加的信息即可

/**
  * 添加学生
  * @param student 学生对象
  * @return 原值返回
  * @author lzh
  */
@PostMapping("/addStudent")
@ResponseBody
public Student addStudent(@RequestBody Student student){
System.out.println(student);
    return student;
}

随意创建主类运行生成接口文档文件夹

public class GenerateClass {
    public static void main(String[] args) {
        DocsConfig config = new DocsConfig();
        config.setProjectPath("D:\\wisdom\\wmsutil"); //项目根目录
        config.setProjectName("wmsutil"); //项目名称
        config.setApiVersion("V1.0"); //声明版本
        config.setDocsPath("C:\\Users\\wisdom21111\\Desktop"); // 生成文档放置目录
        config.setAutoGenerate(Boolean.TRUE); //配置自动生成
        Docs.buildHtmlDocs(config);
    }
}

下图是生成的文档文件夹，打开index.html即可看到所有接口

 接口预览：

        对于JApiDocs，虽然是无侵入式，但只能事后生成文档提供查阅。接下来介绍的Swagger，它可以伴随开发过程生成文档，便于前端及时查阅调用。

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>

创建配置类，不同controller可分别创建Docket方便归类。

@Configuration
@EnableSwagger2
public class Swagger2 {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("仓储系统")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.wisdom.wmsutil"))
                .paths(PathSelectors.regex("/api/test/**"))
                .build();
    }
    //扫描指定包com.wisdom.wmsutil下的的指定请求路径/api/test/**生成文档
    @Bean
    public Docket createapi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("后台系统")
                .apiInfo(htApiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(SwaggerDocument.class))
              //.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                .build();
    }
    //扫描指定的类上注解 @SwaggerDocument
    //@SwaggerDocument是自定义注解

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("仓储系统")
                .description("仅供开发环境使用")
                .termsOfServiceUrl("http://www.baidu.com")
                .contact(new Contact("lzh","https://blog.youkuaiyun.com/sdaulzh","1812430893@qq.com"))
                .version("1.0")
                .build();
    }

    private ApiInfo htApiInfo(){
        return new ApiInfoBuilder()
                .title("后台系统")
                .description("仅供开发环境使用")
                .termsOfServiceUrl("http://www.baidu.com")
                .contact(new Contact("lzh","https://blog.youkuaiyun.com/sdaulzh","1812430893@qq.com"))
                .version("1.0")
                .build();
    }
}

@SwaggerDocument自定义注解，注解添加到controller类上即可

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface SwaggerDocument {
}

注解方法，使用到的注解有@Api @ApiOperation @ApiParam,注意@ApiParam和@RequestParam / @RquestBody需要配合使用

@Controller
@RequestMapping("/api/test")
@Api(tags="测试控制类")
public class TestController {
    @GetMapping("/helloworld")
    @ApiOperation(value="返回原值方法")
    @ResponseBody
    public String helloworld(@ApiParam(name="str",value="字符串参数",required = true) @RequestParam(value = "str",required = true) String str){
        System.out.println(str);
        return str;
    }
}

启动项目，访问 localhost:${server.port}/swagger-ui.html

预览界面：

---

2022年3月3日13点58分更新swagger使用注解方式实现扫描接口