Attribute Macro poem_openapi::API

#[API]

Define a OpenAPI schema

Operation parameters

Attribute	description	Type	Optional
path	HTTP uri.	string	N
method	HTTP method. The possible values are “get”, “post”, “put”, “delete”, “head”, “options”, “connect”, “patch”, “trace”.	string	N
deprecation	Operation deprecated	bool	Y
tag	Operation tag	string	Y

Operation argument parameters

Attribute	description	Type	Optional
name	Parameter name. When this value is set, it means that this is an OpenAPI parameter type.	string	Y
in	Where to parse the parameter. The possible values are “query”, “path”, “header”, “cookie”.	string	Y
extract	It means that this parameter is a Poem extractor.	bool	Y
desc	Argument description	string	Y
deprecation	Argument deprecated	bool	Y

Examples

use poem_openapi::{
    payload::{Json, PlainText},
    Request, Schema, API, Response,
};

#[derive(Schema)]
struct Pet {
    id: String,
    name: String,
}

#[derive(Request)]
enum CreatePetRequest {
    /// This request receives a pet in JSON format(application/json).
    CreateByJSON(Json<Pet>),
    /// This request receives a pet in text format(text/plain).
    CreateByPlainText(PlainText),
}

#[derive(Response)]
enum CreatePetResponse {
    /// Returns when the pet is successfully created.
    #[oai(status = 200)]
    Ok,
    /// Returns when the pet already exists.
    #[oai(status = 409)]
    PetAlreadyExists,
}
 
struct PetAPI;
 
#[API]
impl PetAPI {
    /// Create a new pet.
    #[oai(path = "/pet", method = "post")]
    async fn create_pet(
        &self,
        #[oai(name = "TOKEN", in = "header")] token: String,
        req: CreatePetRequest
    ) -> CreatePetResponse {
        todo!() 
    }
}