định nghĩa mô hình tài liệu không có máy chủ với các trường tùy chọn?

Question

Tôi muốn xác định các mô hình yêu cầu và phản hồi. Tôi sử dụng Framework với AWS serverless và tất cả mọi thứ tôi nhìn thấy khuyến cáo sử dụng serverless-aws-documentation

Các README nói rằng tôi cần phải có dòng này trong custom.documentation.models.MODELNAME

schema: ${file(models/error.json)} 

Nhưng họ không có một tập tin ví dụ về models/error.json để sử dụng làm đường cơ sở.

Trong ví dụ thực tế serverless.yml họ có một định nghĩa như thế này:

- 
    name: DoSomethingRequest 
    contentType: "application/json" 
    schema: 
    type: array 
    items: 
     type: string 

này không cung cấp đủ chi tiết cho những gì tôi đang cố gắng để làm.

---

Mục tiêu của tôi là có lược đồ được xác định cho một mảng đối tượng chuỗi, thông báo và mã trạng thái. Tuy nhiên, thông báo và mã trạng thái là tùy chọn. Đây cũng có thể là một phần của các mô hình khác và nếu có thể tôi không muốn lặp lại định nghĩa của chúng cho từng mô hình.

nỗ lực hiện tại của tôi là:

- 
    name: ReturnArrayResponse 
    contentType: "application/json" 
    schema: 
    type: array 
    itemsArray: 
     type: string 
    message: 
     type: string 
    statusCode: 
     type: number 

Tôi nghĩ rằng điều này sẽ làm những gì tôi muốn, nhưng làm thế nào tôi có thể có message và statusCode là tùy chọn và lặp lại hai mặt hàng này trong các mô hình khác của tôi?

Tôi rất hài lòng với giải pháp yml mà tôi có thể đưa vào tệp serverless.yml hoặc tệp json mà tôi có thể tham chiếu.

Answer 1

Bao gồm một tập tin

Trong ví dụ được đưa ra, error.json có thể chứa bất kỳ giản đồ hợp lệ nào. Vì vậy, một cái gì đó đơn giản như này là tốt:

{"type":"object","properties":{"message":{"type":"string"}}}

Nó cũng tốt để bao gồm các thuộc tính như $schema và title:

{ 
    "$schema" : "http://json-schema.org/draft-04/schema#", 
    "title" : "Error Schema", 
    "type" : "object", 
    "properties" : { 
    "message" : { "type" : "string" }, 
    "statusCode": { "type": "number" }, 
    "itemsArray": { 
     "type": "array", 
     "items": { 
      "type": "string" 
     } 
    } 
    } 
} 

Điều này đặc biệt có ích khi bạn có các mô hình đã được xác định trong AWS, nhưng bạn không có yaml không có máy chủ để xây dựng chúng. Bạn có thể chỉ cần sao chép lược đồ ra khỏi bảng điều khiển AWS, dán json vào một tệp và sử dụng cú pháp schema: ${file()} được đề cập trong câu hỏi. Theo như tôi có thể nói bất cứ điều gì mà bạn có thể nhận được giao diện điều khiển AWS để chấp nhận sẽ làm việc.

DRY

Tôi không biết một cách để tham khảo mô hình từ bên trong các mô hình khác trong một file serverless, nhưng bạn có thể sử dụng phương pháp tương tự như các tác giả plugin, và chỉ cần đặt bất cứ điều gì bạn cần tái sử dụng bên ngoài của models và một nơi nào đó dễ sử dụng hơn. Tác giả plugin sử dụng commonModelSchemaFragments.

Vì vậy, nếu bạn có một số mảnh vỡ như vậy:

commonModelSchemaFragments: 
    # defining common fragments means you can reference them with a single line 
    StringArrayFragment: 
     type: array 
     items: 
      type: string 
    HttpResponse: 
     type: object 
     properties: 
     message: 
      type: string 
     statusCode: 
      type: number  

Bạn có thể tham khảo những mảnh vỡ trong các mô hình như thế này:

- 
    name: HttpStatusResponse 
    contentType: "application/json" 
    schema: 
     type: object 
     properties: 
      serverResponse: 
      ${self:custom.commonModelSchemaFragments.HttpResponse} 
      messageArray: 
      ${self:custom.commonModelSchemaFragments.StringArrayFragment} 

thuộc tính đánh dấu tùy chọn

Bạn có thể thực hiện điều này bằng cách đánh dấu các thuộc tính là required. Chỉ cần cung cấp danh sách tất cả các thuộc tính, ngoại trừ những thuộc tính bạn muốn là tùy chọn. Giản đồ json cho rằng trông như thế này:

{ 
    "type": "object", 
    "required": ["message"], 
    "properties": { 
     "optionalMessage": { 
      "type": "string" 
     }, 
     "message": { 
      "type": "string" 
     } 
    } 
} 

mà bạn sẽ xây dựng bằng cách sử dụng YAML như thế này trong tập tin serverless của bạn:

- 
    name: OptionalResponse 
    contentType: "application/json" 
    schema: 
     type: object 
     required: 
     - "message" 
     properties: 
     message: 
      type: string 
     optionalMessage: 
      type: string 

Lưu ý về yêu cầu xác nhận

Đánh dấu các thuộc tính required hoặc optional chỉ là vấn đề nếu yêu cầu xác thực cơ thể được bật:

Tôi không biết cách bật xác thực yêu cầu bằng bất kỳ cú pháp không có máy chủ đặc biệt nào. Có vẻ như bạn có thể làm điều này trong phần resources, nhưng tôi chưa thử. Source.

Answer 2

Chỉ cần một đoán (đăng nó như là một câu trả lời để duy trì định dạng) - tổ chức cấp cao nhất của bạn trong lược đồ phải là một object, không phải là một array, một cái gì đó như thế này:

schema: 
     type: object 
     properties: 
     items: 
      type: array 
      items: 
      type: string 
     message: 
      type: string 
     statusCode: 
      type: number