如何在OpenAPI 3中正确定义404响应以适配OWASP ZAP工具

I get exactly where you're coming from—you shouldn't have to waste time documenting every possible invalid endpoint, and ZAP's complaint about unanticipated 404 responses is frustrating. The good news is OpenAPI 3 has a clean solution for this scenario using wildcard paths to cover all undefined endpoints in one go.

Here's How to Implement It #

1. First, Reuse Error Responses (Optional but Recommended) #

To keep your spec clean, define reusable 404 and generic error responses in the components section. This avoids repeating the same schema across multiple paths:

components:
  responses:
    NotFound:
      description: The requested resource doesn't exist
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    UnexpectedError:
      description: Something went wrong on the server
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  # Keep your existing schemas (Foo, Error) here

2. Add a Wildcard Path for All Undefined Endpoints #

Add a special wildcard path {+path} to your paths section. This matches any endpoint that isn't explicitly defined in your spec. For each HTTP method your server supports (GET, POST, etc.), link to the reusable responses we just created:

paths:
  # Keep your existing /Foo/ path definition here
  "{+path}":
    # This extension tells code generators to ignore this path (so you don't get useless client code)
    x-codegen-ignore: true
    get:
      responses:
        "404":
          $ref: "#/components/responses/NotFound"
        default:
          $ref: "#/components/responses/UnexpectedError"
    post:
      responses:
        "404":
          $ref: "#/components/responses/NotFound"
        default:
          $ref: "#/components/responses/UnexpectedError"
    # Add PUT, DELETE, or other methods your server supports here

Why This Works #

• The {+path} wildcard is an OpenAPI 3 standard that matches any path not explicitly listed in your spec—whether that's /Bar/, /Foo/InvalidSubpath/, or anything else.
• When ZAP scans these undefined endpoints, it'll now see the wildcard path's response definitions, so it won't flag the 404 as a "non-compliant" response anymore.
• The x-codegen-ignore flag ensures tools like OpenAPI Generator don't treat this wildcard as a real API endpoint (no need to generate code for paths that don't exist!).

Full Modified YAML Example #

openapi: "3.0.0"
paths:
  /Foo/:
    get:
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Foo"
        default:
          description: Errors
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  "{+path}":
    x-codegen-ignore: true
    get:
      responses:
        "404":
          $ref: "#/components/responses/NotFound"
        default:
          $ref: "#/components/responses/UnexpectedError"
    post:
      responses:
        "404":
          $ref: "#/components/responses/NotFound"
        default:
          $ref: "#/components/responses/UnexpectedError"
    put:
      responses:
        "404":
          $ref: "#/components/responses/NotFound"
        default:
          $ref: "#/components/responses/UnexpectedError"
    delete:
      responses:
        "404":
          $ref: "#/components/responses/NotFound"
        default:
          $ref: "#/components/responses/UnexpectedError"
components:
  responses:
    NotFound:
      description: The requested resource doesn't exist
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    UnexpectedError:
      description: Something went wrong on the server
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  schemas:
    Foo:
      type: object
      required:
        - name
      properties:
        name:
          type: string
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
        message:
          type: string
        data:
          type: object

Quick Notes #

• Only add HTTP methods to the wildcard path that your server actually supports. If you don't handle PUT requests, you can skip that section.
• Double-check that the media type (e.g., application/json) in the wildcard response matches exactly what your server returns for 404s—mismatches will still trigger ZAP errors.

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