头痛的接口文档应该这样来写

最新推荐文章于 2024-08-09 16:00:42 发布

不安分的猿人

最新推荐文章于 2024-08-09 16:00:42 发布

阅读量1k

点赞数

分类专栏：技术分享编程学习资源程序员

本文链接：https://blog.youkuaiyun.com/huaairen/article/details/103076042

版权

本文探讨了在项目开发中接口文档维护的问题及其重要性。提出了三种解决方案：集成Swagger插件，让前端直接查看；使用springfox将接口文档转换为html/pdf；以及自定义注解动态生成接口文档。详细介绍了每个方案的实现步骤，并提供了示例代码和项目链接。通过自动化接口文档管理，提升前后端协作效率。

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

自动生成接口文档

一、开头

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

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

解决方案一：项目集成 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

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-L2pBmFv7-1573740697982)()]

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:/