我们公司有一个REST约定/指南,如果资源是一个集合,则在REST资源的URI上使用尾随斜杠。
GET /<resources>/
列出资源GET /<resources>/<resourceId>
获取特定资源POST /<resources>/
创建资源PUT /<resources>/<resourceId>
替换资源PATCH /<resources>/<resourceId>
更新资源DELETE /<resources>/<resourceId>
删除资源
注意尾部的/
以列出资源和创建资源。
本准则的目的是向API使用者传达资源是一个集合。我正试图通过在API规范中包含尾部斜杠来实现这一点。重要的是要注意,API在响应实际请求时不需要严格控制尾部斜杠--这更像是一个文档。
我有一个API项目,它使用Swashbuckle.aspNetCore来生成OpenAPI规范,我正在努力寻找一种干净的方法来实现这一点。
使用属性路由时,将忽略尾部斜杠。下面是控制器上的Route
属性:[Route("api/v{version:apiVersion}/schools/")]
但是,在Open API规范中,路径缺少结尾的斜杠:
openapi: 3.0.1
info:
title: LMS.API
version: '1.0'
paths:
/api/v1/schools:
post:
tags:
- Schools
字符串
有什么办法可以做到这一点吗?
1条答案
按热度按时间xmq68pz91#
我不认为这是容易可行的任何工具,是建立/坚持/强制REST API公约。
原因是您所确定的结尾斜杠约定/准则违背了常见的REST设计原则。
这不仅仅是我的观点,但可以在REST API Design Rulebook, by Mark Massé,第12页中查找:
«URI中不应包含尾随斜杠(/):作为URI路径中的最后一个字符,正斜杠(/)没有添加语义值,可能会引起混淆。REST API不应该期望结尾的斜杠,也不应该将它们包含在它们提供给客户端的链接中。