Apistos  

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

Apistos由以下crate组成：

• apistos：actix-web包装器，用于生成OpenAPI v3.0.3文档文件
• 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-plugins：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/）是赫菲斯托斯（Ἥφαιστος，希腊神话中的铁匠、木匠、工匠和冶金之神，也被一些人视为技术之神）和API（在法语中发音为/a.p.i/）之间的文字游戏。

Apistos

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

安装

[dependencies]
#schemars = "0.8"
# 遗憾的是，我们目前依赖于一个分支来修复枚举的多重展平问题，相关PR可以在这里找到：https://github.com/GREsau/schemars/pull/264
schemars = { package = "apistos-schemars", version = "0.8" }
apistos = "0.3"

使用示例

使用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
}

完整示例请参见示例宠物商店。

功能标志

未来计划

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

替代方案

文章

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

关于我们

apistos由Netwo提供。

我们将这个crate用于我们的内部需求，因此我们致力于维护它，但我们不能提供任何额外的保证。使用时请自行承担风险。

虽然我们不会投资于我们不需要的任何功能，但我们欢迎接受你可能提出的任何拉取请求。

我们是一家总部位于法国的全远程公司，在电信行业运营。如果你有兴趣了解更多，请随时访问我们的职业页面。