search

Apipie / apipie-rails

Ruby on Rails API documentation tool
Apache License 2.0
2.47k stars 463 forks source link

Swagger 2: Components Response `required: true` is not valid swagger #941

Open simonireilly opened 2 months ago

simonireilly commented 2 months ago

Description

Path parameters are singleton resources, and have the schema of required: true to specify their _require_ment

paths:
  /users/{userId}:
    get:
      summary: Get a user by ID
      parameters:
        - in: path
          name: userId
          schema:
            type: integer
          required: true
          description: Numeric ID of the user to get

Schema response components and request bodies use the required: [] syntax to specify which of the fields in their object structure must be provided.

Assertion

The popular redocly CLI replaced the depreacted swagger cli and can be used to lint the produced swagger 2.

npx @redocly/cli lint doc/apidoc/schema_swagger_json.json

Benefit

Once there are far fewer errors generated in the swagger 2 file, the errors which are important for user action will be far easier to see, and act upon.

Fix

When generating swagger from ApiPie remove the required: true generated output from the JSON for request bodies and response bodies, but preserve the array definition

mathieujobin commented 2 months ago

Thank you for opening this well described issue.

Can you open a Pull request with the necessary changes?

jaynetics commented 1 month ago

it seems to be as easy as removing this line, but i'm a bit unsure what is right here because the official json schema of 2.0 says a boolean is valid...