html请求接口_自动生成接口文档

最新推荐文章于 2024-04-08 08:09:24 发布

weixin_39974409

最新推荐文章于 2024-04-08 08:09:24 发布

阅读量782

点赞数

文章标签： html请求接口 java接口文档生成工具 java接口文档示例怎么根据接口文档写接口自动生成研发文档

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

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

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

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

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

项目添加swagger 依赖

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

启动项目，访问链接：http://localhost:8080/swagger-ui.html

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

在项目根目录打包，打包命令如下：

mvn clean package

SwaggerConfig.java

@EnableSwagger2

Swagger2PdfTest.java

@Test

targetasciidoc 就是生成的文档目录，包括 html 和 pdf 文档。

项目地址：https://github.com/nitianziluli/swagger2pdf

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

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

接口上添加注解如下：

@ApiAction

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

@GetMapping

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

项目地址：https://github.com/dakuohao/api-doc

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

“不安分的猿人”对工作的一些思考！

关注