专栏首页不安分的猿人超简单-自动生成接口文档

超简单-自动生成接口文档

一、开头

开发的小伙伴应该会遇到这个问题吧!

项目设计阶段写的接口文档,需求的不断的改动,导致前期定义的接口已面目全非。如果没有及时更新接口文档,那么这些接口文档对前端开发人员将是一场灾难!由于项目紧急,是没有时间完善接口文档,我们该如何提高前后端的开发效率呢?

解决方案一:项目集成 Swagger 插件,前端人员访问 Swagger 生成的接口文档,查看和使用接口。

解决方案二:项目集成 Swagger 插件,在项目打包的时候,生成 html/pdf 形式的接口文档,供其他人使用。

解决方式三:在接口上添加一套自定义注解,指定请求 url,请求方式,请求参数,返回参数等信息,再通过前端页面呈现。

二、实战

1.项目集成 Swagger 依赖,访问接口文档

项目添加swagger 依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

启动项目,访问链接:

http://localhost:8080/swagger-ui.html

2.项目集成 springfox 依赖,生成 html/pdf 形式的接口文档

原理:项目加载 swagger 依赖后,可以生成web的接口测试页面,访问 /v2/api-docs 这个接口 ,会返回 json 字符串,包括所有控制类的接口的定义,然后通过 springfox 将 json 数据按照格式转化为 html 或者 pdf 文档。

2.1示例代码

在项目根目录打包,打包命令如下:

mvn clean package

SwaggerConfig.java

@EnableSwagger2
@Configuration
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfig {

    @Bean
    public Docket restApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .securitySchemes(asList(
                        new OAuth(
                            "petstore_auth",
                            asList(new AuthorizationScope("write_pets", "modify pets in your account"),
                                    new AuthorizationScope("read_pets", "read your pets")),
                                Arrays.<GrantType>asList(new ImplicitGrant(new LoginEndpoint("http://petstore.swagger.io/api/oauth/dialog"), "tokenName"))
                        ),
                        new ApiKey("api_key", "api_key", "header")
                ))
                .select()
                .paths(Predicates.and(ant("/**"), Predicates.not(ant("/error")), Predicates.not(ant("/management/**")), Predicates.not(ant("/management*"))))
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger Petstore")
                .description("Petstore API Description")
                .contact(new Contact("TestName", "http:/test-url.com", "test@test.de"))
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                .version("1.0.0")
                .build();
    }
}

Swagger2PdfTest.java

@Test
public void createSpringfoxSwaggerJson() throws Exception {
        String outputDir = System.getProperty("io.springfox.staticdocs.outputDir");
        logger.info("swagger.json文件存放路径:{}", outputDir);

        // 这里是生成当前项目的swagger.json
        MvcResult mvcResult = this.mockMvc.perform(get("/v2/api-docs")
                .accept(MediaType.APPLICATION_JSON))
                .andExpect(status().isOk())
                .andReturn();
        MockHttpServletResponse response = mvcResult.getResponse();
        String swaggerJson = response.getContentAsString();
        logger.info("swagger json为:{}", swaggerJson);
        Files.createDirectories(Paths.get(outputDir));
        try (BufferedWriter writer = Files.newBufferedWriter(Paths.get(outputDir, "swagger.json"),
                StandardCharsets.UTF_8)) {
            writer.write(swaggerJson);
        }
    }

2.2运行效果

target\asciidoc\ 就是生成的文档目录,包括 html 和 pdf 文档。

2.3示例项目

项目地址:

https://github.com/nitianziluli/swagger2pdf

3.自定义动态生成接口文档

原理:在对外暴露的接口上添加一套自定义注解。注解可指定接口名称,请求 url,请求方式,请求参数,请求参数类型,返回参数,返回参数类型等信息。通过解析 controller 类上注解和方法上的注解,生成获取所有对外暴露方法的定义的接口,然后通过 web 页面呈现所有接口定义。

3.1示例代码

a.定义一套注解,标记controller名称,接口基本信息,接口请求参数,接口响应参数。

接口上添加注解如下:

    @ApiAction(name = "获取用户信息", mapping = "/user/{id}", method = Method.GET)
    @ApiReqParams(type = ParamType.URL_PARAM, value = {
            @ApiParam(name = "id", dataType = DataType.STRING, defaultValue = "", description = "用户id")
    })
    @ApiRespParams({
            @ApiParam(name = "code", dataType = DataType.NUMBER, defaultValue = "0", description = "状态编码"),
            @ApiParam(name = "data", dataType = DataType.OBJECT, defaultValue = "null", description = "响应数据", object = "user"),
            @ApiParam(name = "name", dataType = DataType.STRING, defaultValue = "", description = "姓名", belongTo = "user"),
            @ApiParam(name = "age", dataType = DataType.NUMBER, defaultValue = "", description = "年龄", belongTo = "user"),

            @ApiParam(name = "message", dataType = DataType.STRING, defaultValue = "", description = "提示信息")
    })
    @GetMapping("/user/{id}")
    public Result getUserByIDParams(@pathvariable String id) {
        return Result.success(new User("996", "毁灭你们,与你何干!", 22));
    }

b.获取所有接口信息的接口

    @GetMapping("/api/{type}")
    public ApiDoc admin(@PathVariable("type") String type) {
        //是否打开文档功能
        if (openApiDoc) {
            ApiDoc apiDoc = null;
            //后台管理系统
            if (type.equals("admin")) {
                String packageName = "com.demo.web";
                apiDoc = new GeneratorApiDoc()  //工具类,获取所有接口信息
                        .setInfo(//设置文档基本信息
                                new ApiDocInfo()
                                        .setTitle("某某系统后台管理文档")
                                        .setVersion("1.0")
                                        .setDescription("问题描述\n")
                        )
                        .generator(packageName);//指定生成哪个包下controller的文档
            }

3.2运行效果

web前端调用 /api/{type} 接口,效果如下图:

3.3示例项目

项目地址:

https://github.com/dakuohao/api-doc

三、最后

本文的思考来源于工作。项目接口文档本应该就是根据代码同时发布的,在多加一步操作,将生成的接口文档自动部署到服务上,就实现接口文档的自动更新,一劳永逸!

本文分享自微信公众号 - 不安分的猿人(Restless-man),作者:不安分的猿人

原文出处及转载信息见文内详细说明,如有侵权,请联系 yunjia_community@tencent.com 删除。

原始发表时间:2019-11-04

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • SpringCloud 连载(五) : Feign轻松实现Rest接口调用(附视频)

    上期我们讲了SpringCloud中Ribbon负载均衡.学会了现实中一个非常实用的技能.有兴趣的同学可以看一下.

    不安分的猿人
  • 如何优雅的将数据库表逆向生成代码

    作为 Java 开发,数据库操作是不可逃避的问题,最原始的方式可能使用JDBC操作数据库。渐渐的有了对象关系映射的框架。最让人熟知的有 Hibernate、My...

    不安分的猿人
  • SpringCloud 连载(四) : Ribbon负载均衡与自定义算法(附视频)

    上期内容我们讲了Cloud中非常重要的一个知识点Eureka服务注册与发现服务以及Eureka集群,有兴趣的同学可以从公众号中看一下。

    不安分的猿人
  • ARCGIS接口详细说明

    ArcGIS接口详细说明 目录 ArcGIS接口详细说明... 1 1.      IField接口(esriGeoDatabase)... 2 2.     ...

    水击三千
  • 02:SpringBoot整合SpringDataJPA实现数据库的访问(一)

    Spring Data JPA等于在ORM之上又进行了一次封装,但具体的对数据库的访问依然要依赖于底层的ORM框架,Spring Data JPA默认是通过Hi...

    java进阶架构师
  • Web API 文档生成工具 apidoc

    摘要: 原文可阅读 http://www.iocoder.cn/Fight/web-api-doc 「老梁」欢迎转载,保留摘要,谢谢!

    芋道源码
  • Charles"傻瓜式"创建测试接口

    zhaoolee
  • 利用ApiPost一键、快速生成接口文档!女猿也过38节!

    我们可都是正个八经的理工校草和理工女神,研究github、逛逛csdn、写hello world是才我们的拿手菜,写文档是文科生的事情好不啦?(手动吐哇吐)

    骑马的少年
  • Spring核心——上下文与IoC 原

    前面3篇分别介绍了IoC容器与Bean的关系、Bean与Bean之间的关系以及Bean自身的控制和管理。在了解Spinrg核心模式时,一定要谨记他的基本工作元素...

    随风溜达的向日葵
  • 搭建自己的PHP框架心得(三)

    续言 接着完善自己的PHP框架,本次更新的主要内容有: 介绍了异常处理机制 完善了异常和错误处理 数据表跟Model类的映射 异常处理 异常处理:异常处理是编程...

    枕边书

扫码关注云+社区

领取腾讯云代金券