什么是接口文档?
前后端接口文档是用于描述前端应用程序和后端服务器之间通信的规范和约定的文档。在一个典型的前后端分离的应用程序中,前端应用程序和后端服务器通过接口进行数据交换和通信。
接口文档通常包含以下内容:
接口列表:列出了前后端之间可用的所有接口,每个接口通常都有一个唯一的标识符和名称。
接口描述:对每个接口进行详细的描述,包括接口的功能、用途、输入参数、输出结果以及可能的错误情况等。
请求参数:列出了前端发送给后端的请求参数,包括参数名称、类型、是否必需以及可能的取值范围等。
响应结果:定义了后端返回给前端的响应结果的结构和内容,包括返回数据的格式、字段名称、数据类型以及可能的取值范围等。
错误处理:描述了可能出现的错误情况以及对应的错误码、错误信息和处理方式,以帮助前端应用程序正确处理和展示错误信息。
接口示例:提供一些示例请求和响应的数据,以帮助开发人员理解接口的使用方式和预期结果。
接口文档的编写和维护对于前后端开发团队的协作非常重要。它可以作为前后端开发人员之间的沟通工具,确保双方对接口的行为和数据格式有共同的理解,以便高效地进行开发和集成。常见的接口文档格式包括 Swagger(OpenAPI)、API Blueprint、Postman 等。
谁会使用接口文档?
前端开发人员:前端开发人员使用接口文档来了解后端接口的使用方式、输入参数和预期响应,以便正确地发起请求并处理返回结果。接口文档帮助他们理解接口的功能和约定,从而能够与后端进行协作开发。
后端开发人员:后端开发人员使用接口文档作为实现后端接口的指南。接口文档描述了前端期望的请求参数和响应结果,后端开发人员需要根据文档中的规范来设计和实现接口逻辑。
怎么做接口文档?
手写
自动化接口文档生成:自动根据项目代码生成完整的文档和在线调试网页。
比如Swagger、Postman、apifox、apipost等
后端项目整合Swagger + Knife4j
由于 Knife4j本身集成了Swagger,为了方便可以直接集成knife4j
https://doc.xiaominfo.com/docs/quick-start
OpenAPI2(Swagger)规范是Knife4j之前一直提供支持的版本,底层依赖框架为Springfox,此次在4.0版本开始
Knife4j有了新的变化,主要有以下几点:
Springfox版本选择的依然是2.10.5版本,而并非springfox最新3.0.0版本
不支持以Springfox框架为基础的OpenAPI3规范,放弃Springfox项目的后续版本适配支持工作
Spring Boot 版本建议 2.4.0~3.0.0之间
在
pom.xml
文件中引入 knife4j 依赖<dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-openapi2-spring-boot-starter</artifactId> <version>4.1.0</version> </dependency>
配置
application.yml
文件knife4j: enable: true openapi: title: Knife4j官方文档 description: "`我是测试`,**你知道吗** # aaa" email: xiaoymin@foxmail.com concat: 八一菜刀 url: https://docs.xiaominfo.com version: v4.0 license: Apache 2.0 license-url: https://stackoverflow.com/ terms-of-service-url: https://stackoverflow.com/ group: test1: group-name: 分组名称 api-rule: package api-rule-resources: - com.knife4j.demo.new3
最后,访问Knife4j的文档地址:
http://ip:port/doc.html
即可查看文档
注意事项
生产环境下隐藏接口文档
在生产环境下一定要隐藏接口文档,不能给别人访问到!
解决办法:
在生产环境的配置文件application-prod.yml
文件中的 knife4j配置里,添加 production配置:
knife4j:
enable: true
openapi:
title: Knife4j官方文档
description: "`我是测试`,**你知道吗**
# aaa"
email: xiaoymin@foxmail.com
concat: 八一菜刀
url: https://docs.xiaominfo.com
version: v4.0
license: Apache 2.0
license-url: https://stackoverflow.com/
terms-of-service-url: https://stackoverflow.com/
group:
test1:
group-name: 分组名称
api-rule: package
api-rule-resources:
- com.knife4j.demo.new3
production: true # true之后生产环境启动后,就访问不了接口文档
评论区