Suggestion: Use handler type and Rust doc comments for automatic OpenAPI generation instead of requiring a separate docs_fn

[joebnb]

Currently, aide requires providing a second argument in *_with(handler, docs_fn) for OpenAPI documentation. In practice, this can feel redundant and error-prone because:

• The documentation function is maintained separately from the handler, making it easy to get out of sync.
• For internal development or use cases where the main goal is to generate TypeScript clients, manually writing the docs_fn adds extra maintenance without real benefit.

Suggestion:

• Automatically generate OpenAPI documentation from the handler’s input/output types.
• Use Rust doc comments on the handler function or the return types as summary/description in the OpenAPI spec.
• Make the docs_fn optional, so it’s only needed for overriding defaults or providing extra metadata.

Benefits:

• Reduces duplication and maintenance overhead.
• Ensures documentation stays consistent with the code.
• Simplifies the workflow for projects that mainly need type-safe API clients.

Example

struct Todo {
   id: i32,
   // create time comment
   create_time: String
}
/// List all todos
async fn list_todos() -> Json<Vec<Todo>> { ... }

before:

"get": {
  "responses": {
    "200": {
      "description": "",
      "content": {
        "application/json": {
          "example": [
             {
               "id": {...id properties},
               "create_time": { 
                     "type": "string",
                    "format": "date-time",
                    "description": "",
                    "allowEmptyValue": false
                }
             }
          ]
        }
      }
    }
  }
}

Suggested after (automatic doc generation):

"get": {
  "responses": {
    "200": {
      "description": "List all todos",
      "content": {
        "application/json": {
          "example": [
             {
               "id": {...id properties},
               "create_time": { 
                     "type": "string",
                    "format": "date-time",
                    "description": "create time comment",
                    "allowEmptyValue": false
                }
             }
          ]
        }
      }
    }
  }
}

This would make aide more ergonomic and closer to “documentation as code” philosophy.

[Wicpar]

you have https://docs.rs/axum-typed-routing/latest/axum_typed_routing/