Attribute Macro api_operation

#[api_operation]

Operation attribute macro implementing PathItemDefinition for the decorated handler function.

use std::fmt::Display;
use actix_web::web::Json;
use actix_web::http::StatusCode;
use actix_web::ResponseError;
use core::fmt::Formatter;
use apistos::actix::CreatedJson;
use apistos::{api_operation, ApiComponent, ApiErrorComponent};
use schemars::JsonSchema;
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize, Debug, Clone, JsonSchema, ApiComponent)]
pub struct Test {
  pub test: String
}

#[derive(Serialize, Deserialize, Debug, Clone, ApiErrorComponent)]
#[openapi_error(
  status(code = 405, description = "Invalid input"),
)]
pub enum ErrorResponse {
  MethodNotAllowed(String),
}

impl Display for ErrorResponse {
  fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
    todo!()
  }
}

impl ResponseError for ErrorResponse {
  fn status_code(&self) -> StatusCode {
    todo!()
  }
}

#[api_operation(
  tag = "pet",
  summary = "Add a new pet to the store",
  description = r###"Add a new pet to the store
    Plop"###,
  error_code = 405
)]
pub(crate) async fn test(
  body: Json<Test>,
) -> Result<CreatedJson<Test>, ErrorResponse> {
  Ok(CreatedJson(body.0))
}

#[api_operation(...)] options:

• skip a bool allowing to skip documentation for the decorated handler. No component strictly associated to this operation will be document in the resulting openapi definition.
• skip_args = "..." an optional list of arguments to skip. Apistos will not try to generate the documentation for those args which prevent errors linked to missing ApiComponent implementation.
• deprecated a bool indicating the operation is deprecated. Deprecation can also be declared with rust #[deprecated] decorator.
• operation_id = "..." an optional operation id for this operation. Default is the handler’s fn name.
• summary = "..." an optional summary
• description = "..." an optional description
• tag = "..." an optional list of tags associated with this operation (define tag multiple times to add to the list)
• security_scope(...) an optional list representing which security scopes apply for a given operation with
  • name = "..." a mandatory name referencing one of the security definitions
  • scope(...) a list of scopes applying to this operation
• error_code = 00 an optional list of error codes to document only theses
• consumes = "..." allow to override body content type
• produces = "..." allow to override response content type

If summary or description are not provided, a default value will be extracted from the comments. The first line will be used as summary while the rest will be part of the description.

For example:

use actix_web::web::Json;
use std::fmt::Display;
use actix_web::http::StatusCode;
use actix_web::ResponseError;
use core::fmt::Formatter;
use apistos::actix::CreatedJson;
use apistos::{api_operation, ApiComponent, ApiErrorComponent};
use schemars::JsonSchema;
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize, Debug, Clone, JsonSchema, ApiComponent)]
pub struct Test {
  pub test: String
}

#[derive(Serialize, Deserialize, Debug, Clone, ApiErrorComponent)]
#[openapi_error(
  status(code = 405, description = "Invalid input"),
)]
pub enum ErrorResponse {
  MethodNotAllowed(String),
}

impl Display for ErrorResponse {
  fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
    todo!()
  }
}

impl ResponseError for ErrorResponse {
  fn status_code(&self) -> StatusCode {
    todo!()
  }
}

#[api_operation(
  tag = "pet",
  summary = "Add a new pet to the store",
  description = r###"Add a new pet to the store
    Plop"###,
)]
pub(crate) async fn test(
  body: Json<Test>,
) -> Result<CreatedJson<Test>, ErrorResponse> {
  Ok(CreatedJson(body.0))
}

is equivalent to

use std::fmt::Display;
use actix_web::web::Json;
use actix_web::http::StatusCode;
use actix_web::ResponseError;
use core::fmt::Formatter;
use apistos::actix::CreatedJson;
use apistos::{api_operation, ApiComponent, ApiErrorComponent};
use schemars::JsonSchema;
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize, Debug, Clone, JsonSchema, ApiComponent)]
pub struct Test {
  pub test: String
}

#[derive(Serialize, Deserialize, Debug, Clone, ApiErrorComponent)]
#[openapi_error(
  status(code = 405, description = "Invalid input"),
)]
pub enum ErrorResponse {
  MethodNotAllowed(String),
}

impl Display for ErrorResponse {
  fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
    todo!()
  }
}

impl ResponseError for ErrorResponse {
  fn status_code(&self) -> StatusCode {
    todo!()
  }
}

/// Add a new pet to the store
/// Add a new pet to the store
/// Plop
#[api_operation(
  tag = "pet",
)]
pub(crate) async fn test(
  body: Json<Test>,
) -> Result<CreatedJson<Test>, ErrorResponse> {
  Ok(CreatedJson(body.0))
}