这是一个提高工作效率的VSCode插件，能够从使用Rust开发的后台接口，一键生成Swagger文档，然后可以导入YAPI中，快速创建接口的文档。

一、开发背景

我们为什么要开发这个VSCode插件？开发出来能够带来什么样的好处？

我们开发后台接口时，一般是先定义这个接口，在开发团队内部对接口的描述进行评审，前后端开发者取得一致的意见之后，再进行接口实际程序的开发。

这样一方面开发的接口方向不会错，另一方面前端开发者也可以第一时间针对接口描述开始进行开发工作了。

这就要求我们文档先行，先写好接口的描述文档。

以往，我们都是直接在YAPI上先进行接口文档的编写工作，取得一致意见后再进行接口的开发。

但是感觉直接在YAPI上编写接口文档，效率不是很高；而且编写好文档，已经出了一次力，然后再按照接口文档开发接口的程序，这又是出了第二次力了。能不能把这两次力合并成只出一次力呢？

于是我们想到，首先直接在程序里定义好接口，然后从程序直接生成接口文档。

这样做有以下几个好处：

程序写起来比在YAPI上写接口文档要稍快一点；
写程序时更难发生拼写错误，生成的文档也就不会有了；
详尽的文档来源于详尽的程序注释，这样会促使我们把程序注释写得完整详尽，代码更好维护一点；
导出文档需要程序有规范的接口输入输出参数的类型定义，这样会促使我们把程序也写得更规范一点；
今后对于接口有什么修改，也可以方便快速地导出到文档上面来；

二、安装插件

插件使用的演示

在VSCode插件里面直接搜索clia，应该就能看到插件“Clia Swagger Generator”了。

安装即可。

在插件的扩展设置里，有 basePath、host、schemes 三项是需要我们进行填写的。

三、编写接口

一个合适导出的Rust接口是什么样子的？

如下 Rust 代码：

use ntex::http::StatusCode;
use ntex::web::types::Json;
use ntex::web::{self, Error, HttpRequest, HttpResponse};
use serde::{Deserialize, Serialize};

/// 注册新开发者接口的请求。
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RegisterDeveloperJson {
    /// 开发者注册邮箱
    pub dev_email: String,
    /// 开发者名称
    pub dev_name: String,
    /// 开发者类型：个人(individual) | 企业(enterprise)
    pub dev_type: String,
    /// 开发者设定的密码
    pub user_password: String,
}

/// 注册新开发者接口的响应格式。
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RegisterDeveloperResponse {
    /// 返回代码
    pub code: i32,
    /// 返回消息
    pub msg: String,
    /// 返回数据
    pub data: RegisterDeveloperData,
}

/// 注册新开发者接口的数据格式。
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RegisterDeveloperData {
    /// 创建的开发者ID
    pub developer_id: u64,
}

/// 注册新开发者。
///
/// 请求 JSON 示例：
///
/// <pre><code>
/// {
///     "dev_email": "someone@somecompany.com",
///     "dev_name": "Some One",
///     "dev_type": "individual",
///     "user_password": "abcd1234"
/// }
/// </code></pre>
/// 
/// 返回 JSON 示例：
/// 
/// <pre><code>
/// {
///     "code":0,
///     "msg":"success",
///     "data":{
///         "developer_id":2349
///     }
/// }
/// </code></pre>
///
/// @returns RegisterDeveloperResponse
///
#[web::post("/mp/register-developer")]
pub async fn register_developer(
    req: HttpRequest,
    body: Json<RegisterDeveloperJson>,
) -> Result<HttpResponse, Error> {
    log::debug!("{:?}", req);
    log::debug!("{:?}", body);

    // response
    Ok(HttpResponse::build(StatusCode::OK)
        .content_type("application/json; charset=utf-8")
        .body(
            r#"{
            "code":0,
            "msg":"success",
            "data":{
                "developer_id":2349
            }
        }"#,
        ))
}