Utoipa隐式支持部分serde属性。有关更多信息，请参阅文档。

安装

将最小依赖声明添加到Cargo.toml。

[dependencies]
utoipa = "4"

要启用更多功能，例如使用actix框架扩展，可以将依赖项定义为以下内容。

[dependencies]
utoipa = { version = "4", features = ["actix_extras"] }

注意！要与Swagger UI一起使用utoipa，可以使用utoipa-swagger-ui crate。

示例

创建一个结构体，或者它也可以是一个枚举。向它添加ToSchema derive宏，以便它可以注册为OpenAPI模式。

use utoipa::ToSchema;

#[derive(ToSchema)]
struct Pet {
   id: u64,
   name: String,
   age: Option<i32>,
}

创建一个处理程序，用于处理您的业务逻辑，并在其上添加path proc属性宏。

mod pet_api {
    /// Get pet by id
    ///
    /// Get pet from database by pet id
    #[utoipa::path(
        get,
        path = "/pets/{id}",
        responses(
            (status = 200, description = "Pet found successfully", body = Pet),
            (status = NOT_FOUND, description = "Pet was not found")
        ),
        params(
            ("id" = u64, Path, description = "Pet database id to get Pet for"),
        )
    )]
    async fn get_pet_by_id(pet_id: u64) -> Pet {
        Pet {
            id: pet_id,
            age: None,
            name: "lightning".to_string(),
        }
    }
}

Utoipa支持响应中的http StatusCode。

该属性宏将创建另一个名为__path_前缀+处理程序函数名的结构体。因此，当您在不同的文件中实现some_handler函数并想要导出它时，请确保模块中的__path_some_handler也可以从根访问。

使用以下OpenApi derive proc宏将上述Schema和端点与OpenAPI模式相关联。

use utoipa::OpenApi;

#[derive(OpenApi)]
#[openapi(paths(pet_api::get_pet_by_id), components(schemas(Pet)))]
struct ApiDoc;

println!("{}", ApiDoc::openapi().to_pretty_json().unwrap());

这将生成类似以下内容的API文档

{
  "openapi": "3.1.0",
  "info": {
    "title": "application name from Cargo.toml",
    "description": "description from Cargo.toml",
    "contact": {
      "name": "author name from Cargo.toml",
      "email": "author email from Cargo.toml"
    },
    "license": {
      "name": "license from Cargo.toml"
    },
    "version": "version from Cargo.toml"
  },
  "paths": {
    "/pets/{id}": {
      "get": {
        "tags": [
          "pet_api"
        ],
        "summary": "Get pet by id",
        "description": "Get pet from database by pet id",
        "operationId": "get_pet_by_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Pet database id to get Pet for",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64",
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Pet found successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Pet"
                }
              }
            }
          },
          "404": {
            "description": "Pet was not found"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Pet": {
        "type": "object",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "age": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32"
          },
          "id": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "name": {
            "type": "string"
          }
        }
      }
    }
  }
}

在运行时修改OpenAPI

您可以通过直接使用生成的类型或使用Modify trait来在运行时修改生成的OpenAPI。

直接通过类型修改生成的OpenAPI。

#[derive(OpenApi)]
#[openapi(
    info(description = "My Api description"),
)]
struct ApiDoc;

let mut doc = ApiDoc::openapi();
doc.info.title = String::from("My Api");

您甚至可以将生成的OpenApi转换为OpenApiBuilder。

let builder: OpenApiBuilder = ApiDoc::openapi().into();

有关如何通过它修改生成的OpenAPI的示例，请参阅Modify trait。

超越表面

• 有关如何通过Swagger UI提供OpenAPI文档的详细信息，请参阅utoipa-swagger-ui crate。
• 浏览示例以获取更全面的示例。
• 检查 IntoResponses 和 ToResponse 以获取派生响应的示例。
• 有关 OpenAPI 安全性的更多信息，请参阅 安全文档。
• 在构建时将生成的 API 文档输出到文件。请参阅 问题 214 评论。

常见问题解答

Swagger UI 从构建的二进制文件返回 404 NotFound

这很可能是由于 RustEmbed 没有将 Swagger UI 嵌入可执行文件造成的。这是自然的，因为 RustEmbed 库在默认情况下不会在调试构建中嵌入文件。为了解决这个问题，您可以执行以下操作之一。

1. 以 --release 模式构建您的可执行文件
2. 或将 debug-embed 特性标志添加到您的 Cargo.toml 中的 utoipa-swagger-ui。这将启用 debug-emebed 特性标志，对于 RustEmbed 也是如此。有关更多信息，请参阅 此处 和 此处。

在此处找到 utoipa-swagger-ui 的 特性标志。

如何为外部类型实现 ToSchema？

有几种方法可以解决这个问题，具体细节请参见 此处。

如何使用 Rust 的类型别名？

目前这是不可能的，因为没有方法来评估 proc macro 代码生成过程中可见的类型标记背后的实际类型。如果可以实施全局别名注册表，这可能在将来实现。有关此问题的相关 issue 请参阅 #766。

自动发现 OpenAPI 架构和路径？

目前没有内置的解决方案来自动发现 OpenAPI 类型，但幸运的是，有一个非常不错的 crate 可以为您完成这项工作，名为 utoipauto。

许可证

根据您的选择，受 Apache 2.0 或 MIT 许可证的约束。

除非您明确声明，否则您提交给包含在此 crate 中的任何贡献都将双许可，没有任何额外的条款或条件。