接口文档编写注意事项

接口文档编写注意事项

字段方面

①不需要的字段、逻辑中固定值的字段(可写死的字段)不提供
②逻辑上可以合并的字段合并
例如:当一个互斥条件下,分别返回了两个字段,这个时候就可以在这个基础上将两个字段合并成一个字段
③字段对应的业务逻辑要标清楚
例如:某些情况下,响应返回的某个字段,在不同的情况下返回的结果是不一样的,调用方根据这个字段返回值需要有不同的响应,这个时候就需要标注下,该字段不同的响应值,调用方需要做的逻辑
在这里插入图片描述
④是否非空,长度,枚举类型标清楚
⑤条件必填对应的原因写清楚

接口方面

①接口调用流程,从哪里调到哪里(调用方/提供方)(请求方/响应方)
②接口是同步还是异步
③接口请求地址

报文

①请求参数
②响应参数
③公共参数
④小对象参数(附加域参数)

应答码

①明确成功状态
②错误码、对应错误原因表格

http

①http请求响应终态码(成功状态码/失败状态码)
②超时时间
③使用json、xml或者其他格式

网络

①专线还是公网
②是否需要白名单,网络准入

安全

①加签验签证书,及加签验签流程
②加密解密证书,及加密解密流程
③证书交换形式:接口/系统/邮件

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/pingmian/12544.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

Android之实现《用户隐私政策》《服务条款》等文字点击可查看协议内容的超链接功能

一、步骤 1、控件 <TextViewandroid:id"id/tv_privacy"android:layout_width"match_parent"android:layout_height"wrap_content"android:text"协议提示文字"android:textSize"12sp"android:textColor"color/color…

(十)Python基础练习题一(50道选择题)#Python

本文整理了Python基础知识相关的练习题&#xff0c;共50道&#xff0c;适用于刚入门初级Python想巩固基础的同学。来源&#xff1a;如荷学数据科学题库&#xff08;技术专项-Python一&#xff09;。 1&#xff09; 2&#xff09; 3&#xff09; 4&#xff09; 5&#xff09; 6…

搞懂Servlet(1)- 介绍

介绍Servlet 今天&#xff0c;我们都意识到创建动态网页的必要性。动态网页就是网页内容会随着时间变化&#xff0c;或者内容会根据请求参数的不同而变化。如果你使用java编程&#xff0c;很幸运的是有一种使用Java生成动态网页的方式-Java Servlet。但是&#xff0c;在这之前…

Jetson orin scv3环境配置

记不清当时是怎么配置的环境了&#xff0c;难搞 python环境的安装&#xff1a; conda create -n scv3 python3.8安装torch 和torchvision 去这里找到jetpack版本对应的torch ,我的jetpack5.1.3&#xff0c;并且环境需要安装pytorch-lightning1.7.3,&#xff0c;对应的torch版本…

【web网页开发制作】Html+Css+Js游戏主题特效及轮播效果网页作业天涯明月刀(7页面附源码)

HTMLCSSJS游戏主题轮播效果 &#x1f354;涉及知识&#x1f964;写在前面✨特效展示特效1、轮播幻灯效果特效2和3、鼠标悬浮及点击效果 &#x1f367;一、网页主题&#x1f333;二、网页效果Page1、首页Page2、游戏简介Page3、新闻中心Page4、互动专区Page5、视听盛宴Page6、用…

ctfshow parse_url wp

第一关 这个parse_url函数就是解析URL并且进行拆分的 $url "https://www.example.com/path/to/page?param1value1&param2value2";$parsed_url parse_url($url);print_r($parsed_url); Array ([scheme] > https[host] > www.example.com[path] > /p…

【论文复刻】 堆叠柱状图变形

复刻了一下这篇论文里的fig4a&#xff1a;Impacts of COVID-19 and fiscal stimuli on global emissions and the Paris Agreement | Nature Climate Change 效果图&#xff1a;​ 主要步骤&#xff1a; 1. 数据准备&#xff1a;随机赋值 2. 数据处理&#xff1a;计算了一个…

机器学习中常用的几种距离——欧式、余弦等

目录 一、欧式距离&#xff08;L2距离&#xff09;二、曼哈顿距离&#xff08;L1距离&#xff09;三、汉明距离四、余弦相似度 一、欧式距离&#xff08;L2距离&#xff09; &#xff08;1&#xff09;二维空间的距离公式&#xff08;三维空间的在这个基础上类推&#xff09;&…

linux内核debug(二)在线调试内核kdb/kgdb工具使用及环境搭建

目录 一、引言 二、kgdb调试 ------>2.1、kgdb板端配置 ------------>2.1.1、添加编译内核参数 ------------>2.1.2、配置 ------>2.2、kgdb本地调试环境搭建 ------------>2.2.1、串口工具 ------------>2.2.2、连接板端 ------>2.3、kgdb调试 …

31、Flink 的 DataStream API 数据流算子详解

1.算子 可以通过算子将一个或多个 DataStream 转换成新的 DataStream&#xff0c;也可以将多个数据转换算子合并成一个复杂的数据流拓扑。 2.数据流转换 a&#xff09;Map DataStream → DataStream 输入一个元素&#xff0c;转换后输出一个元素&#xff0c;示例将输入流中…

LeetCode hot100-40-N

543. 二叉树的直径 给你一棵二叉树的根节点&#xff0c;返回该树的 直径 。二叉树的 直径 是指树中任意两个节点之间最长路径的 长度 。这条路径可能经过也可能不经过根节点 root 。两节点之间路径的 长度 由它们之间边数表示。这题尝试做了一下&#xff0c;有几个测试案例通不…

4.StableDiffusion各项参数解读

经过前期的努力&#xff0c;我想大家都已经生成了自己的第一张AI作品&#xff0c;但是充满了随机性&#xff0c;每次都是不一样的&#xff0c;并且有时候生成的图片效果还不是很让人满意&#xff0c;暂且先不要着急&#xff0c;先跟着本篇文章&#xff0c;学习一些每个选项和参…

Google Chrome GPU渲染抓包

非安全模式启动 "C:\Program Files\Google\Chrome\Application\chrome.exe" --ignore-certificate-errors --allow-running-insecure-content --disable-web-security 配置环境 set RENDERDOC_HOOK_EGL0 "C:/Program Files/Google/Chrome/Application/chrom…

Windows本地部署直播录屏利器Bililive-go并实现远程添加直播间录屏

&#x1f308;个人主页: Aileen_0v0 &#x1f525;热门专栏: 华为鸿蒙系统学习|计算机网络|数据结构与算法 ​&#x1f4ab;个人格言:“没有罗马,那就自己创造罗马~” 文章目录 1. Bililive-go与套件下载1.1 获取ffmpeg1.2 获取Bililive-go1.3 配置套件 2. 本地运行测试3. 录屏…

【OpenCV 基础知识 2】灰度化图片

文章目录 cvCreateImagecvCvtColor完整示例代码 cvCreateImage 使用OpenCV库在Delphi中创建一个灰度图像。让我解释一下&#xff1a; gray_image : cvCreateImage(cvGetSize(image), IPL_DEPTH_8U, 1);cvGetSize(image): 这个函数返回给定图像&#xff08;在这里是image&…

【MySQL】事务及其隔离性/隔离级别

目录 一、事务的概念 1、事务的四种特性 2、事务的作用 3、存储引擎对事务的支持 4、事务的提交方式 二、事务的启动、回滚与提交 1、准备工作&#xff1a;调整MySQL的默认隔离级别为最低/创建测试表 2、事务的启动、回滚与提交 3、启动事务后未commit&#xff0c;但是…

MVP产品设计与数据指标

MVP&#xff08;minimum viable product&#xff0c;最小化可行产品&#xff09;概念最早由埃里克莱斯提出&#xff0c;刊载于哈弗商业评论&#xff0c;并有出版物《精益创业》 和常规产品不同&#xff0c;MVP更侧重于对未知市场的勘测&#xff0c;用最小的代价接触客户的方法…

学习Nginx(一):基础

介绍 Nginx是一个高性能的HTTP和反向代理的web服务器&#xff0c;它的设计重点是高并发、高性能和低内存消耗。它常被用于提供静态内容、负载均衡和作为Web服务器。 Nginx具有以下功能和特点&#xff1a; 静态文件服务&#xff1a;作为一个Web服务器&#xff0c;Nginx可以处…

GPT-4o可以用了

方法&#xff1a;挂日本/新加坡的梯子就可以了&#xff0c;打开就会弹出以下的弹窗。不过不知道可以用多久呢&#xff1f; 2024/5/15

木里风景文化|基于SSM+vue的木里风景文化管理平台的设计与实现(源码+数据库+文档)

木里风景文化管理平台 目录 基于SSM&#xff0b;vue的木里风景文化管理平台的设计与实现 一、前言 二、系统设计 三、系统功能设计 1 系统功能模块 2 管理员功能模块 3 用户功能模块 四、数据库设计 五、核心代码 六、论文参考 七、最新计算机毕设选题推荐 八、源…