前往小程序,Get更优阅读体验!
立即前往
首页
学习
活动
专区
工具
TVP
发布
社区首页 >专栏 >【大家的项目】Poem-openapi

【大家的项目】Poem-openapi

作者头像
MikeLoveRust
发布2021-09-08 10:12:52
1.2K0
发布2021-09-08 10:12:52
举报

尽管有不少朋友已经知道我这几天在做什么,但当Poem-openapi的第一版准时完成,并且完全按照刚开始的想法正常工作时,我还是按捺不住内心的激动希望跟大家分享。

注意:Poem-openapi只支持Poem,所以你如果希望使用它,Poem是必要的依赖,而且我不会考虑支持其它的web框架。😎

据我所知这是Rust语言里第一个用过程宏来实现OpenAPI规范的库,它的工作方式和Async-graphql非常的像,以类型安全的代码来编写符合OpenAPI规范的API并自动生成文档。过程宏的使用完全IDE友好,你绝对不会直接用到过程宏生成的任何代码,避免了IDE满屏幕的红线,或者没法自动完成(我很看重这个,脱离IDE的自动完成我不会写代码)。😂

下面我以一个小例子来介绍它是如何使用的:

这是一个简单的用户管理API实现(别管它有没有什么实际价值,也别告诉我oai这个名字很奇怪,这是官方起的简称,不怪我),我们只看它如何使用。😁

每一个接口都需要定义Request和Response类型,除非它不接收或者返回任何内容。

create_user接口创建一个用户,由于它的请求对象类型是Json,所以它只支持content-typeapplication/json的请求。返回的CreateUserResponse定义了不同状态码对应的响应类型。

所有API宏描述的操作都会自动生成OpenAPI 3.0规范的文档,你可以clone仓库 https://github.com/poem-web/poem-openapi ,然后执行cargo run --example users,浏览器打开http://localhost:3000,就能看到一个非常奢华的Swagger UI(尽管我觉得它离GraphQL Playground的易用度还差得远)。😎

use std::collections::HashMap;

use poem_openapi::{payload::Json, types::Password, OpenAPI, Response, Schema, API};
use tokio::sync::Mutex;

/// Create user schema
#[derive(Debug, Schema, Clone, Eq, PartialEq)]
struct User {
    /// Id
    id: String,
    /// Name
    name: String,
    /// Password
    password: Password,
}

/// Update user schema
#[derive(Debug, Schema, Clone, Eq, PartialEq)]
struct UpdateUser {
    /// Name
    name: Option<String>,
    /// Password
    password: Option<Password>,
}

#[derive(Response)]
enum CreateUserResponse {
    /// Returns when the user is successfully created.
    #[oai(status = 200)]
    Ok,
    /// Returns when the user already exists.
    #[oai(status = 409)]
    UserAlreadyExists,
}

#[derive(Response)]
enum FindUserResponse {
    /// Return the specified user.
    #[oai(status = 200)]
    Ok(Json<User>),
    /// Return when the specified user is not found.
    #[oai(status = 404)]
    NotFound,
}

#[derive(Response)]
enum DeleteUserResponse {
    /// Returns when the user is successfully deleted.
    #[oai(status = 200)]
    Ok,
    /// Return when the specified user is not found.
    #[oai(status = 404)]
    NotFound,
}

#[derive(Response)]
enum UpdateUserResponse {
    /// Returns when the user is successfully updated.
    #[oai(status = 200)]
    Ok,
    /// Return when the specified user is not found.
    #[oai(status = 404)]
    NotFound,
}

#[derive(Default)]
struct Api {
    users: Mutex<HashMap<String, User>>,
}

#[API]
impl Api {
    /// Create a new user
    #[oai(path = "/users", method = "post", tag = "user")]
    async fn create_user(&self, user: Json<User>) -> CreateUserResponse {
        let mut users = self.users.lock().await;
        if users.contains_key(&user.0.id) {
            return CreateUserResponse::UserAlreadyExists;
        }
        users.insert(user.0.id.clone(), user.0);
        CreateUserResponse::Ok
    }

    /// Find user by id
    #[oai(path = "/users/:user_id", method = "get", tag = "user")]
    async fn find_user(
        &self,
        #[oai(name = "user_id", in = "path")] user_id: String,
    ) -> FindUserResponse {
        let users = self.users.lock().await;
        match users.get(&user_id) {
            Some(user) => FindUserResponse::Ok(Json(user.clone())),
            None => FindUserResponse::NotFound,
        }
    }

    /// Delete user by id
    #[oai(path = "/users/:user_id", method = "delete", tag = "user")]
    async fn delete_user(
        &self,
        #[oai(name = "user_id", in = "path")] user_id: String,
    ) -> DeleteUserResponse {
        let mut users = self.users.lock().await;
        match users.remove(&user_id) {
            Some(_) => DeleteUserResponse::Ok,
            None => DeleteUserResponse::NotFound,
        }
    }

    /// Update user by id
    #[oai(path = "/users/:user_id", method = "put", tag = "user")]
    async fn put_user(
        &self,
        #[oai(name = "user_id", in = "path")] user_id: String,
        update: Json<UpdateUser>,
    ) -> UpdateUserResponse {
        let mut users = self.users.lock().await;
        match users.get_mut(&user_id) {
            Some(user) => {
                if let Some(name) = update.0.name {
                    user.name = name;
                }
                if let Some(password) = update.0.password {
                    user.password = password;
                }
                UpdateUserResponse::Ok
            }
            None => UpdateUserResponse::NotFound,
        }
    }
}

#[tokio::main]
async fn main() {
    poem::Server::bind("127.0.0.1:3000")
        .await
        .unwrap()
        .run(
            OpenAPI::new(Api::default())
                .title("poem-openapi")
                .version("0.1.0")
                .server_with_description("http://localhost:3000", "localhost")
                .tag_with_description("user", "Operations about user")
                .ui_path("/"),
        )
        .await
        .unwrap();
}

要完全支持Open API规范中定义的特性还有不少功能要做,比如JsonSchema的所有校验器,认证,权限等等,如果你觉得这个库有用,并且希望能够为它贡献自己的力量,我非常欢迎!😁

https://github.com/poem-web/poem-openapi

本文参与 腾讯云自媒体分享计划,分享自微信公众号。
原始发表:2021-09-03,如有侵权请联系 cloudcommunity@tencent.com 删除

本文分享自 Rust语言学习交流 微信公众号,前往查看

如有侵权,请联系 cloudcommunity@tencent.com 删除。

本文参与 腾讯云自媒体分享计划  ,欢迎热爱写作的你一起参与!

评论
登录后参与评论
0 条评论
热度
最新
推荐阅读
领券
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档