Apistos −

一个暴露 OAS 3.0 模型以及类似于 paperclip 的 actix-web 包装器的 OpenAPI 文档工具。

Apistos 由以下 Crates 组成

• apistos: 生成 OpenAPI v3.0.3 文档文件的 actix-web 包装器
• apistos-core: 包围 OpenAPI v3.0.3 的特性和常见模型的集合
• apistos-gen: 从 Rust 模型生成 OpenAPI v3.0.3 文档的宏实用工具
• apistos-models: 基于 schemars 定义的 OpenAPI v3.0.3 模型，具有 Schema
• apistos-plugins：扩展 Apistos 的特性和工具
• apistos-rapidoc：Apistos 和 RapiDoc 之间的桥梁，适用于 actix。
• apistos-redoc：Apistos 和 Redoc 之间的桥梁，适用于 actix。
• apistos-scalar：Apistos 和 Scalar 之间的桥梁，适用于 actix。
• apistos-shuttle：允许您在 Shuttle 上运行带有 Apistos 文档的 actix-web 服务器。
• apistos-swagger-ui：Apistos 和 Swagger UI 之间的桥梁，适用于 actix。

查看我们的 示例项目。

Apistos 是什么意思

Apistos（发音为 /a.p.i.stos/）是 Héphaïstos（希腊神赫淮斯托斯，铁匠、木匠、工匠、冶金之神，一些人认为也可以视为技术之神）和 API（法语中发音为 /a.p.i/）之间的双关语。

Apistos

• 安装
• 用法示例
• 功能标志
• 替代方案
• 关于我们

安装

[dependencies]
#schemars = "0.8"
# sadly we currently rely on a fork to fix multiple flatten for enums, related PR can be found here: https://github.com/GREsau/schemars/pull/264
schemars = { package = "apistos-schemars", version = "1.0.0-alpha.2" }
apistos = "1.0.0-pre-release.4"

用法示例

使用 apistos 类型包装您的常规 actix-web 应用程序。

这些类型中的大多数都是 actix-web 的直接替换类型。

use std::fmt::Display;
use actix_web::{App, HttpServer, ResponseError};
use actix_web::http::StatusCode;
use actix_web::middleware::Logger;
use actix_web::web::Json;
use apistos::actix::CreatedJson;
use apistos::api_operation;
use apistos::ApiComponent;
use apistos::ApiErrorComponent;
use apistos::app::OpenApiWrapper;
use apistos::spec::Spec;
use apistos::web::{post, resource, scope};
use apistos_models::info::Info;
use core::fmt::Formatter;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use std::error::Error;
use std::net::Ipv4Addr;

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

#[derive(Serialize, Deserialize, Debug, Clone, ApiErrorComponent)]
#[openapi_error(
  status(code = 403),
  status(code = 404),
  status(code = 405, description = "Invalid input"),
  status(code = 409)
)]
pub enum ErrorResponse {
  MethodNotAllowed(String),
  NotFound(String),
  Conflict(String),
  Unauthorized(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))
}

#[actix_web::main]
async fn main() -> Result<(), impl Error> {
  HttpServer::new(move || {
    let spec = Spec {
      info: Info {
        title: "An API".to_string(),
        version: "1.0.0".to_string(),
        ..Default::default()
      },
      ..Default::default()
    };

    App::new()
        .document(spec)
        .wrap(Logger::default())
        .service(scope("/test")
            .service(
              resource("")
                  .route(post().to(test))
            )
        )
        .build("/openapi.json")
  })
      .bind((Ipv4Addr::UNSPECIFIED, 8080))?
      .run()
      .await
}

查看完整示例，请参阅 示例 petstore。

功能标志

下一步是什么

• 使用ApiErrorComponent派生宏处理错误模式

替代方案

文章

• 可以在medium上找到公告文章。它充当Apistos的教程。

关于我们

Apistos由Netwo提供。

我们使用此crate满足内部需求，因此致力于其维护，但我们无法提供任何额外的保证。请自行承担风险使用。

虽然我们不会投资我们不需要的功能，但我们乐于接受您可能提出的任何pull request。

我们是一家总部位于法国的全远程电信行业公司。如果您想了解更多信息，请随时访问我们的职业页面。