首页
学习
活动
专区
工具
TVP
发布
精选内容/技术社群/优惠产品,尽在小程序
立即前往

REST文档是否必须包含每个请求参数的所有可能值?

REST文档不必包含每个请求参数的所有可能值。REST(Representational State Transfer)是一种基于HTTP协议的软件架构风格,它强调资源的概念和统一接口的设计。在RESTful API的设计中,文档通常用于描述API的使用方法和资源的访问方式。

对于请求参数,REST文档应该包含必需的参数以及可选参数的说明,以便开发者了解如何正确构造请求。文档应该提供参数的名称、类型、是否必需、默认值、限制条件等信息,以便开发者能够正确地使用API。

然而,对于参数的所有可能值,REST文档通常不会详细列出。这是因为参数的取值范围可能非常广泛,或者是动态变化的。如果文档要包含每个参数的所有可能值,那么文档将变得庞大且难以维护。相反,文档应该提供参数的合法取值范围的概述或示例,以便开发者了解参数的大致取值范围。

对于开发者来说,他们可以通过文档中提供的参数信息和示例,结合实际需求和业务逻辑,来确定参数的具体取值。在实际开发中,开发者可以通过与后端开发团队的沟通和协作,进一步了解参数的取值范围和限制条件。

总结起来,REST文档应该包含请求参数的必需信息和可选信息,但不必详细列出每个参数的所有可能值。文档应该提供参数的名称、类型、是否必需、默认值、限制条件等信息,以便开发者正确使用API。

页面内容是否对你有帮助?
有帮助
没帮助

相关·内容

Microsoft REST API指南

虽然每个服务通常提供特定于语言框架来包装其API,但它们所有操作最终都归结为HTTP请求。微软必须支持广泛客户端和服务,不能依赖于每个开发环境都有丰富框架。...[]译者注:GUID太长而且不易于理解和阅读,如果不是必须,尽量少用此字段。 7.4 支持方法 客户端必须可能使用正确HTTP动词来执行操作,并且必须考虑是否支持此操作幂等性。...| 是否应用了首选项请求头中指示首选项 | | ETag | 当请求资源具有实体标记时 | ETag响应头字段为请求变量提供实体标记的当前。...“details”键值对 必须是JSON对象数组,其中必须包含“code”和“message”键值对,还可能包含“target”键值对,如上所述。...delta 必须包含每个与指定条件新匹配实体条目,并且必须每个不再符合条件实体包含“@removed”条目。

4.6K10

REST 服务中支持 CORS

REST 服务中启用对 CORS 支持有两个部分:启用 REST 服务以接受部分或所有 HTTP 请求 CORS 标头。。编写代码,使 REST 服务检查 CORS 请求并决定是否继续。...例如,可以提供一个允许列表,其中包含包含受信任脚本域。 IRIS 为文档目的提供了一个简单默认实现;此默认实现允许任何 CORS 请求。...此操作重新生成调度类,导致行为实际变化。没有必要详细了解 dispatch 类,但请注意以下变化:它现在包含 HandleCorsRequest 参数。...如果 HandleCorsRequest 参数为 0(默认),则对所有调用禁用 CORS 标头处理。在这种情况下,如果 REST 服务接收到带有 CORS 标头请求,则服务会拒绝该请求。...此属性必须是自定义类完全限定名称。

2.6K30
  • BaaS API 设计规范

    主要包含两个方面的规范:API 本身设计规范、API 帮助文档编写规范。 1.2. 参考资料 《Representational State Transfer (REST)》 1.3....主体输入 考虑到接口扩展性,所有API输入只能接受一般 JSON 对象作为输入参数,同时也只能输出一个 JSON 对象。 当输入输出是单一、数组时,需要使用一个对象对其进行封装。...动作:使用 GET 来进行请求。 · 其它查询 每一个特殊查询,都需要提供相应特殊查询地址。必须参数以URI Part 形式给出,可选参数则以查询字符串形式给出。...帮助文档内容规范 向外公布每个API帮助说明,必须至少包含以下几项: · API 简介 · 请求 o 说明请求方法、地址。...o URI 参数:如果 URI 中某部分是动态,请使用大括号说明:api/values/{id}。 o URI 查询参数:如果 URI 地址有参数,描述各项参数与说明。每个参数是否可选。

    3.1K111

    只需使用VS CodeREST客户端插件即可进行API调用

    您最后要注意是 test.http 文件中请求 ### ,这是请求之间分隔符,只要在每个请求之间插入 ### 就可以在文件中包含任意数量请求。...一旦他们点击了链接并登陆页面,一个 GET 请求就会被启动,以确保邮件中包含用于重置密码令牌是有效,这就是它可能样子。...在撰写本文时,REST Client 文档说它支持六种流行身份验证类型,包括对 JWT 身份验证支持,这是我应用程序在所有受保护路由上都依赖身份验证类型。...DELETE 示例 经过我上面提供其他例子,这个示例应该很简单 这个 DELETE 需要查询参数是 username,这样它就知道到底要删除数据库中哪个用户,而且还需要验证这个用户是否有资格提出这个请求...我强烈建议您查阅文档,以了解 REST Client 所有功能,它非常强大。 REST Client 文档:https://marketplace.visualstudio.com/items?

    8.4K20

    你确定你 REST API 真的符合 REST 规范?

    RESTful API 背后思想是遵循REST 规范中描述所有架构规则和限制方式进行开发。然而,实际上,这在实践中基本上是不可能。 一方面,REST 包含了太多模糊和模棱两可定义。...所有资源描述,包括标识符、HTTP 方法、所有输入参数、响应代码和主体数据类型,以及指向定义链接。 所有可用于输入或输出定义,以 JSON 模式格式。...该键包含所有的 JSON 模型。模型可能包含交叉引用($ref),因此,如果你有任何嵌入式模型(例如,Blog {posts: Post[]}),则需要将它们展开,以便在验证中使用。...基本上,这些插件允许你为必须包含在 JSON 对象中特定模型提供字段列表,以及附加规则。例如,你可以重命名字段并动态计算它们。...例如,POST 和PATCH 请求中可用字段列表必须严格限制,PATCH 通常将所有字段标记为可选。描述响应模型可以更加自由。

    27820

    详解微服务技术中进程间通信

    实现基于请求/响应交互比较复杂:请求/响应风格交互要求一些实现上工作,每个请求消息必须包含一个应答通道ID和关联ID,服务将相关ID包含在响应消息中,并发送到响应通道,客户端就通过这个相关ID来将响应和请求匹配起来...Leonard Richardson给出了一个很有用REST成熟度模型,包含如下一些级别: 级别0:客户端通过发送基于HTTPPOST请求到唯一URL服务端,每个请求指定要执行动作,动作对象(...级别1:支持资源概念,为了在一个资源上执行动作,客户端需要在POST请求中指定执行动作和所有参数。 级别2:API使用HTTP动词来执行动作:GET用来获取,POST用来创建,PUT用来修改。...请求要求参数请求体,如果有,还需要指定动作参数,这样服务就可以利用页面系统一些基础设施,如缓存GET请求。...一个Thrift接口包含一个或多个服务,定义服务与定义Java接口类似,是一些强输入方法集合,Thrift方法可以定义城返回一个(也可能是void),或者定义成单向方法。

    48440

    微服务架构中进程间通信

    由于您无法强制客户端立即升级,服务必须支持较旧版本API一段时间。如果您使用基于HTTP机制(如REST),则一种方法是将版本号嵌入到URL中。每个服务实例可能同时处理多个版本。...实现基于请求/响应交互复杂性 - 请求/响应风格交互需要一些实现工作。每个请求消息必须包含响应通道和想着标识符。该服务将包含相关ID响应消息写入响应通道。...例如,GET请求返回资源表示形式,可能是XML文档或JSON对象形式。 POST请求创建一个新资源,PUT请求更新一个资源。...类似地,在XML中,属性由命名元素和表示。这使得消息消费者能够挑选其感兴趣并忽略其余。因此,消息格式微小变化可以轻松地向后兼容。 XML文档结构由XML模式指定。...使用基于文本消息格式缺点是消息往往是冗长,特别是XML。因为消息是自描述每个消息除了它们之外还包含属性名称。另一个缺点是解析文本开销。因此,您可能需要考虑使用二进制格式。

    2.5K50

    《ASP.ENT Core 与 RESTful API 开发实战》-- 读书笔记(第1章)

    后面的参数部分 锚部分,也称片段,在 “#” 后面的内容,用于指明一个资源特定位置 当 HTTP 服务器对请求返回响应时,它不仅仅返回资源本身,也会在响应中指明资源内容类型(Content Type...4xx:客户端错误:请求包含语法错误或请求内容不正确 5xx:服务端错误:服务器在处理请求过程中发生了错误 1.3 REST 最佳实践 首先,在实现 RESTful 系统时,应正确地使用 HTTP...中可以使用中划线 ”-“ 来增加其可读性 URI 中不应使用下划线 ”_“ ,因为会使得 URI 点击时下划线不可见 URL 末尾不应包含斜线 ”/“ ,因为没意义而且可能造成歧义 1.4 其他问题...: 数字 字符串 逻辑 数组 对象 null XML 与 HTML 语言很相似,包含标签、属性等元素,而且有非常严格层次结构,一个标签必须同时具有起始标签与结束标签,允许自定义标签 XML 文档必须包含根元素...,该元素是文档中其他元素父元素,文档所有元素形成一棵文档树 XML 每个标签之间还必须要正确嵌套,另外,标签名区分大小写,标签允许包含一个或多个属性,每个属性必须使用引号 JSON 比 XML

    90810

    Rest Notes-REST架构元素

    但是它丧失了信息隐藏优点,并且要求发送者和接收者都必须理解相同数据类型 REST提供所有三种选项一个混合体,通过以一种数据格式移交资源表述来进行通信,可以基于接收者能力和所期待格式以及内容中动态选择所使用数据格式...(通常用来验证消息完整性) 元数据以名称-形式出现,名称对应于一个定义结构和语义标准。...也用于提供请求参数,或覆盖某些连接元素默认行为 表述数据格式被称为媒体类型(media type),发送者能够将一个表述包含在一个消息中发给接收者,接收者根据消息中控制数据和媒体类型性质对该消息进行处理...所有REST交互都是无状态,这一限制得到了四个功能: 它使得连接器无须在请求之间保持应用状态,改善了可伸缩性,降低了物理资源消耗 它允许对交互进行并行处理,处理机制无须理解交互语义 它允许中间件孤立查看和理解一个请求...,当对服务进行动态“编排”时这个是必须 它强制每个请求必须包含可能会影响到一个已缓存响应可重用性所有信息 上面列表前两种都是很容易理解,第三种缓存连接器可以位于客户或服务器连接器接口处,以便保存当前交互可缓存响应

    80750

    微服务技术中进程间通信

    实现基于请求/响应交互比较复杂:请求/响应风格交互要求一些实现上工作,每个请求消息必须包含一个应答通道ID和关联ID,服务将相关ID包含在响应消息中,并发送到响应通道,客户端就通过这个相关ID来将响应和请求匹配起来...REST使用HTTP方法来操作资源,通过URL来引用资源。比如,GET请求会返回一个资源信息,返回结果用XML文档或者JSON对象来表示,POST请求创建一个资源,PUT请求是更新一个资源。...Leonard Richardson给出了一个很有用REST成熟度模型,包含如下一些级别: 级别0:客户端通过发送基于HTTPPOST请求到唯一URL服务端,每个请求指定要执行动作,动作对象(...级别1:支持资源概念,为了在一个资源上执行动作,客户端需要在POST请求中指定执行动作和所有参数。 级别2:API使用HTTP动词来执行动作:GET用来获取,POST用来创建,PUT用来修改。...一个Thrift接口包含一个或多个服务,定义服务与定义Java接口类似,是一些强输入方法集合,Thrift方法可以定义城返回一个(也可能是void),或者定义成单向方法。

    61110

    3、进程间通信

    该服务为缺少请求属性提供默认,并且客户端忽略所有多余响应属性。使用 IPC 机制和消息格式非常重要,他们可以让您轻松地演化 API。 但有时候,您必须对 API 作出大量不兼容更改。...消息代理程序必须高度可用,否则系统可靠性将受到影响。 实施基于请求/响应式交互复杂性 请求/响应式交互需要做些工作来实现。每个请求消息必须包含应答通道标识符和相关标识符。...REST 使用 HTTP 动词(谓词)来操纵资源,这些资源通过 URL 引用。例如,GET 请求返回一个资源表述形式,可能是 XML 文档或 JSON 对象形式。...每个请求被指定要执行操作、操作目标(如业务对象)以及参数。 级别 1 级别 1 API 支持资源概念。要对资源执行操作,客户端会创建一个 POST 请求,指定要执行操作和参数。...使用基于文本消息格式缺点是消息往往是冗长,特别是 XML。因为消息是自描述每个消息除了它们之外还包含属性名称。另一个缺点是解析文本开销。因此,您可能需要考虑使用二进制格式。

    1.3K20

    Spring Boot从零入门6_Swagger2生成生产环境中REST API文档

    4.3.2 API精细配置 虽然上面我们已经可以控制API显示和分组了,但是对于API一些更详细,对组内API再次归类之类,比如小组描述信息,以及每个API如何去控制它参数说明,返回说明等。...相关参数设置说明如下: name:参数名称,注意一定要与实际方法形参名一致,否则无法生效 value:参数值 defaultValue:参数默认 required:是否为必需项 allowMultiple...请求参数获取:@RequestHeader(代码中接收注解) query : 用于get请求参数拼接。...参数设置说明如下: name: 参数名称 value: 参数值 required: 是否必须项 defaultValue: 默认 type: 参数类型 hidden: 是否因此该参数 @ApiResponses...设置参数有: name:属性名称,需与JavaBean内保持一致 value:属性 notes:说明 dataType:数据类型 required:是否必须 readOnly:是否只读,默认为false

    2.2K20

    Postman 进阶技巧

    Postman 最基本用法,就是开发人员可以在这一步建立一个 API 集合(Collection),其中包含项目的所有 API,这里我们创建了一个叫 Corp 集合,包含所有功能 API: ▲单个请求...之外,我们在 API 中使用相同类型参数也都可以声明为变量,而变量可以用在请求任何部分。...这里我们对返回结果做了两个测试,分别是验证 HTTP 状态码必须是 200 以及检测返回结果中必须包含 access_token 这个属性。...“测试 1”,我们检查了 HTTP 返回状态码为 200,其实针对所有请求,我们可能都需要做这个检查,那么如果不复制粘贴代码,有没有简化方法呢?...businessCode,这样的话,在 Postman Tests 脚本中,可以添加代码直接检查业务层面的返回结果是否成功,例如,我们定义 10000 为业务结果正确返回: pm.test("

    60620

    为什么我使用 GraphQL 而放弃 REST API?

    是否总是希望一次获取所有相关项目?可能不需要,但是还需要添加更多查询参数。也许你不想一次获取所有对象字段。...如果应用程序需要项目有所有者,并且除了每个集合有单独视图显示外,还有一个视图显示所有这些数据聚合?它要么是三个独立 HTTP 请求,要么是一个复杂请求,同时获取所有数据用于聚合。...此外,它非常简单:type块定义新类型,每个包含具有自己类型字段定义。类型可以是非可选,例如String!字段不能有空,而String可以。字段也可以有命名参数,所以TodoList!...请注意,allTodos字段offset参数是缺失。作为可选项,它缺失意味着它有null。如果服务器提供这种模式,文档可能会声明,null偏移量意味着默认情况下应该返回第一页。...查询可以完全控制将要接收实际信息,但是底层 GraphQL 基础设施还必须确保所有必需字段和参数都在那里。

    2.3K30

    Postman 进阶技巧

    Postman 最基本用法,就是开发人员可以在这一步建立一个 API 集合(Collection),其中包含项目的所有 API,这里我们创建了一个叫 Corp 集合,包含所有功能 API:图片 图中重要三个部分...这里我们对返回结果做了两个测试,分别是验证 HTTP 状态码必须是 200 以及检测返回结果中必须包含 access_token 这个属性。...“测试 1”,我们检查了 HTTP 返回状态码为 200,其实针对所有请求,我们可能都需要做这个检查,那么如果不复制粘贴代码,有没有简化方法呢?...env_prod 中,该变量为 https://your.test.env.ip:test_port,然后修改每个请求,将原本 http://localhost:8080 地址换成变量 {{jmixAppUrl...businessCode,这样的话,在 Postman Tests 脚本中,可以添加代码直接检查业务层面的返回结果是否成功,例如,我们定义 10000 为业务结果正确返回:pm.test("Success

    45120

    REST API设计指导——译自Microsoft REST API Guidelines(四)

    日期 | 所有请求| 服务执行时间撮,以RFC 5322日期和时间格式处理响应。这个头必须包含在响应中。格林尼治平均时间(GMT)必须用作该报头时区参考。...具有安全敏感性必填标头(例如,授权标头)可能不适合作为参数;服务所有者应该根据具体情况具体分析。...服务应该有一个相对小数量(约20)错误码可能范围,“所有客户端必须能够处理所有的错误码。大多数服务将需要更大数量更具体错误代码以满足所有的客户端请求。...  “.”名称/必须是JSON对象数组,该数组必须包含“code”和“message”名称/对,并且允许包含“target”名称/对,如上所述。...错误请求可能包含他们json对象任何注释。

    2K50

    Spring Boot实战:集成Swagger2

    API文档描述以及一些全局性配置,对所有接口起作用。...第二个问题:这个请求参应该是直接根据对象反射出来结果,但是不是对象每个属性都是必传,另外参数也不一定满足我们需求,这个能否配置?   ...:参数名称     value:参数说明     required:是否必须     dataType:数据类型     @ApiResponses,@ApiResponse容器,可以包含多个@ApiResponse...我们可以从页面上看到请求参数说明是有的,不过这不是我们预期效果,如果我们参数仅仅是简单类型,这种方式应该没问题,但现在问题是我们请求参数是一个对象,那如何配置呢?...    required:是否必须     example:示例     hidden:是否显示   完成上面的配置后,我们再来看效果: ?

    59250

    Spring Boot实战:集成Swagger2

    API文档描述以及一些全局性配置,对所有接口起作用。...第二个问题:这个请求参应该是直接根据对象反射出来结果,但是不是对象每个属性都是必传,另外参数也不一定满足我们需求,这个能否配置?   ...:参数名称     value:参数说明     required:是否必须     dataType:数据类型     @ApiResponses,@ApiResponse容器,可以包含多个@ApiResponse...我们可以从页面上看到请求参数说明是有的,不过这不是我们预期效果,如果我们参数仅仅是简单类型,这种方式应该没问题,但现在问题是我们请求参数是一个对象,那如何配置呢?...    required:是否必须     example:示例     hidden:是否显示   完成上面的配置后,我们再来看效果: ?

    1.1K100

    使用 OAS(OpenAPI标准)来描述 Web API

    目前行业内有很多API风格, 例如: REST, gRPC, GraphQL, SOAP, RPC等等. 但是每个风格都遵循一些基本设计原则....一个Action可能有多种响应结果, 每种可能响应结果都要在responses属性中描述. 每个响应都以状态码进行标识, 并且必须包含一个description属性....那么使用JSON Schema来描述它就应该是这样: ? 还没完, 我还必须指出属性是否是必填, 然后我再加上一个remark属性, 它不是必填: ?...描述 body 参数 像 POST 这样 Action, 它参数是在请求body里面. body参数需要使用 requestBody属性描述, 看代码: ?...这里面name必须和 {} 里面的一样. in 为 path, 表示是路径参数. 路径参数是必填, 所以 required 为 true. 不然解析器会报错.

    3.5K20

    Springboot实战:集成Swagger2

    API文档描述以及一些全局性配置,对所有接口起作用。...第二个问题:这个请求参应该是直接根据对象反射出来结果,但是不是对象每个属性都是必传,另外参数也不一定满足我们需求,这个能否配置?...@ApiImplicitParams,@ApiImplicitParam容器,可包含多个@ApiImplicitParam注解 @ApiImplicitParam,请求参数属性配置: name:参数名称...value:参数说明 required:是否必须 dataType:数据类型   @ApiResponses,@ApiResponse容器,可以包含多个@ApiResponse注解 @ApiResponse...: value:类说明 description:详细描述 @ApiModelProperty是对具体每个字段属性配置: name:字段名称 value:字段说明 required:是否必须 example

    79320
    领券