如何在Swagger 2.0中建模父字段可选、指定时子字段必选的规则？

Alright, let's figure out how to implement this conditional requirement in Swagger 2.0. You want MyParent to be optional, but if it's included, its two child fields have to be required. Swagger 2.0 gives us a couple of solid ways to handle this—here are the most practical approaches:

1. Use the dependencies Keyword (Most Straightforward) #

Swagger 2.0 supports the dependencies schema property, which lets you define rules like "if property X exists, then Y must be true". For your scenario, we can set up a dependency that enforces MyParent's children are required whenever MyParent itself is present.

Here's how the schema would look:

swagger: '2.0'
info:
  title: Your API Title
  version: 1.0.0
paths:
  /your-endpoint:
    post:
      parameters:
        - in: body
          name: requestBody
          schema:
            type: object
            properties:
              # Add any other top-level properties here
              MyParent:
                type: object
                properties:
                  MyParent_child1:
                    type: string
                  MyParent_child2:
                    type: integer
            # Define the conditional rule
            dependencies:
              MyParent:
                type: object
                required:
                  - MyParent_child1
                  - MyParent_child2

How this works: #

• MyParent remains optional at the top level (since it's not in the root required array).
• The dependencies block says: if MyParent is included in the request, it must match the nested schema where MyParent_child1 and MyParent_child2 are required. This prevents partial MyParent objects from being submitted.

2. Use oneOf for Explicit Scenario Separation #

If you prefer more clarity (or need to add additional conditional logic later), you can use oneOf to split the schema into two distinct, mutually exclusive cases:

1. The request does not include MyParent
2. The request does include MyParent, with both child fields required

Here's the implementation:

swagger: '2.0'
info:
  title: Your API Title
  version: 1.0.0
paths:
  /your-endpoint:
    post:
      parameters:
        - in: body
          name: requestBody
          schema:
            type: object
            oneOf:
              # Case 1: No MyParent field allowed
              - type: object
                properties:
                  # Include all your other top-level properties here
                not:
                  required:
                    - MyParent
              # Case 2: MyParent is present, with required children
              - type: object
                properties:
                  # Include all your other top-level properties here
                  MyParent:
                    type: object
                    required:
                      - MyParent_child1
                      - MyParent_child2
                    properties:
                      MyParent_child1:
                        type: string
                      MyParent_child2:
                        type: integer
                required:
                  - MyParent

How this works: #

• The oneOf keyword ensures the request matches exactly one of the two cases.
• In the first case, we explicitly disallow MyParent using the not keyword.
• In the second case, MyParent is marked as required, and its own schema enforces the child fields are mandatory.

A Quick Note: #

Some older versions of Swagger UI might not fully validate these conditional rules in the interactive editor, but the schema itself is compliant with Swagger 2.0 standards and will work with tools that properly support JSON Schema validation. If you ever upgrade to OpenAPI 3.x, you can use the more intuitive if/then/else keywords for this kind of logic, but the above methods are your best options for Swagger 2.0.

内容的提问来源于stack exchange，提问作者AR1