针对不支持的操作的 HTTP 服务器行为和 REST API 规范

Question

我有一些REST API的规范，并且我也在开发相应API的一些实现。

问题出现了，对于规范中尚未实现的操作，我的实现应该返回什么 HTTP 状态代码（我无法在 405 和 501 之间做出决定）？我应该在 OpenAPI 规范中显示相应的响应吗？

Answer 1

responses

部分来指示端点将返回 501 Not Implemented 响应

paths:
  /ex:
    get:
      summary: Example operation
      description: This operation is not yet implemented.
      responses:
        '501':
          description: Not implemented
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "This operation is not implemented yet."

回复正文：

{
  "error": "This operation is not implemented yet."
}  another example: 

x-api-status: "planned"
x-expected-release: "v2.0"

/get:
  summary: Example operation
  description: |
    This operation is currently not implemented. 
    Planned for future release in **v2.0**.
  x-api-status: "planned"
  x-expected-release: "v2.0"
  responses:
    '501':
      description: Not implemented
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

沙箱：

responses:
  '200':
    description: Stub response for testing
    content:
      application/json:
        schema:
          type: object
          properties:
            data:
              type: string
              example: "Stubbed response: feature not yet implemented."

405 无效 http 方法示例：

responses:
  '405':
    description: Method not allowed
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ErrorResponse'

端点：

 {
  "version": "v1.0",
  "endpoints": {
    "/example": {
      "methods": ["GET"],
      "status": "not implemented"
    },
    "/users": {
      "methods": ["GET", "POST"],
      "status": "implemented"
    }
  }
}