[OpenAPI] Inline schema improvements: optional attributes and `Array<>` syntax

[rsamoilov]

Description

Inline YAML schemas used in @request and @response tags currently have two limitations:

1. No support for optional attributes

When using an inline schema like @response { id: Integer, name: String, email: String }, all attributes are treated as non-required in the generated OpenAPI specification. There is no way to distinguish between required and optional attributes.

The @param tag already supports the ? suffix to mark optional parameters. The same convention should work for inline schema attributes. Attributes without the ? suffix should be marked as required, while attributes with the suffix should be non-required.

For example:

class Api::V1::UsersController < ApplicationController
  # @request { name?: String, email: String, password: String }
  def create
  end
end

Should generate:

schema:
  type: object
  required:
    - email
    - password
  properties:
    name:
      type: string
    email:
      type: string
    password:
      type: string

Note that name is still included in properties (without the ?), but is excluded from the required list.

2. No Array<> syntax for inline schema values

The Array<> syntax is already supported for top-level references (e.g. @response Array<UserResource>), and the [] syntax works inside inline schemas (e.g. { errors: [String] }). However, Array<> is not supported inside inline schemas.

The following should work equivalently:

# Currently supported
# @response 422 { errors: [String] }

# Should also be supported
# @response 422 { errors: Array<String> }

Both should generate:

schema:
  type: object
  properties:
    errors:
      type: array
      items:
        type: string

Tips

• Check the OpenAPI docs to understand how inline schemas, @request, and @response tags work.
• Look at how the inline schema parser currently handles the [] syntax - extending it to also accept Array<> should follow a similar pattern.
• The OpenAPI specification on required properties describes how required works in object schemas.
• Check the architecture doc that shows how Rage's core components interact with each other and outlines the design principles.
• Feel free to ask any questions or request help in the comments below!

[ayushman1210]

@rsamoilov Hey, quick question — for the Array<> support inside inline schemas, should this only cover simple cases like Array or Array, or do we also want to handle something like Array<Array> or arrays of inline objects? Just want to make sure I scope this right before I start.

[rsamoilov]

@rsamoilov Hey, quick question — for the Array<> support inside inline schemas, should this only cover simple cases like Array or Array, or do we also want to handle something like Array or arrays of inline objects? Just want to make sure I scope this right before I start.

With the Array<> syntax, simple cases make the most sense. But generally, it should work the same way [] does, as it's the least surprising behaviour.

[ayushman1210]

@rsamoilov okay,Thanks for the clarification on Array<>.
Can I be assigned to this issue? I'd love to work on it!

[rsamoilov]

Done!