swagger 如何确保作为集合的REST资源的URI中有一个尾随的正斜杠?

yacmzcpb  于 2023-08-05  发布在  其他
关注(0)|答案(1)|浏览(127)

我们公司有一个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

字符串
有什么办法可以做到这一点吗?

xmq68pz9

xmq68pz91#

我不认为这是容易可行的任何工具,是建立/坚持/强制REST API公约。
原因是您所确定的结尾斜杠约定/准则违背了常见的REST设计原则。
这不仅仅是我的观点,但可以在REST API Design Rulebook, by Mark Massé,第12页中查找:
«URI中不应包含尾随斜杠(/):作为URI路径中的最后一个字符,正斜杠(/)没有添加语义值,可能会引起混淆。REST API不应该期望结尾的斜杠,也不应该将它们包含在它们提供给客户端的链接中。

相关问题