poem-web / poem

A full-featured and easy-to-use web framework with the Rust programming language.
Apache License 2.0
3.62k stars 295 forks source link

Assign the description to the request object in OpenAPI #886

Open bruwozniak opened 2 months ago

bruwozniak commented 2 months ago

This fixes an issue where the doc comment description of an e.g. JSON parameter of a request would not show up in the generated API spec.

For example:

#[oai(path = "/users", method = "post", operation_id = "createUser")]
async fn create_user(
    &self,
    /// Parameters required to create a new user
    Json(params): Json<CreateUserParams>,
)

should translate to:

  /users:
    post:
      requestBody:
        description: Parameters required to create a new user
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/CreateUserParams'
        required: true

but without this change description is missing.

bruwozniak commented 1 week ago

@sunli829 could you please take a look? it's a relatively small one