Utoipa 默认部分支持 serde 属性。有关更多详细信息，请参阅 文档。

安装

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

[dependencies]
utoipa = "4"

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

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

**注意**！要使用 utoipa 与 Swagger UI 一起使用，可以使用 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();

请参阅Modify特质以获取如何通过它修改生成的OpenAPI的示例。

深入了解

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

常见问题解答（FAQ）

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

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

1. 以--release模式构建您的可执行文件
2. 或向您的Cargo.toml中的utoipa-swagger-ui添加debug-embed功能标志。这将启用debug-emebed功能标志，同时为RustEmbed。有关更多信息，请参阅此处和此处。

在此处找到utoipa-swagger-ui的功能标志。

有几种方法可以解决这个问题，具体请参阅此处的详细说明。

如何使用Rust的类型别名？

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

如何自动发现OpenAPI模式和路径？

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

许可证

根据您的选择，在Apache 2.0或MIT许可证下授权。

除非您明确说明，否则您提交给包括在此存储库中的任何贡献，都应双重授权，没有任何额外的条款或条件。