mitwald API JavaScript客户端
这个包包含一个JavaScript客户端（大部分是自动生成的） mittwald API。
许可证
版权所有：Mittwald CM Service GmbH & Co. KG
本项目（以及其中的所有NPM软件包）在MIT许可下获得许可； 看到 许可证 文件查看详细信息。
目录表
安装
你可以从普通的NPM注册表中安装这个包：
yarn add @mittwald/api-client
使用
导入客户端：
import { MittwaldAPIV2Client } from "@mittwald/api-client";
要创建客户端实例，可以使用以下工厂方法之一 不同类型的认证：
MittwaldAPIClient.newUnauthenticated()MittwaldAPIClient.newWithToken(apiToken: string)(推荐)MittwaldAPIClient.newWithCredentials(email: string, password: string)( 实际上在后台执行登录，从而返回一个promise)
看看我们的 API的介绍 了解更多信息 如何获取API令牌以及如何开始使用API。
使用v3-next客户机
默认的导入路径公开了v2客户机。使用生产
v3-next 客户端，从 @mittwald/api-client/v3-next 子路径:
import { MittwaldAPIClient } from "@mittwald/api-client/v3-next";
const mittwaldApi = MittwaldAPIClient.newWithToken("your-access-token");
React客户端可以从对应的React子路径中获得：
import { MittwaldAPIClientReact } from "@mittwald/api-client/v3-next/react";
TypeScript的请求和响应类型通过
MittwaldAPIV3Next 名称空间:
import { MittwaldAPIV3Next } from "@mittwald/api-client/v3-next";
这使用了已发布的、非开发的 v3-next 客户端。这个包裹没有
公开 @mittwald/api-client/v3-next-dev 进口路径;这个 v3-next-dev
OpenAPI规范仅用于生成开发构建。
设置请求参数
API请求可能需要这些类型的参数：
- 路径参数
- 头
- 查询参数
- 请求体
路径参数
路径参数是URL路径的可变部分。他们通常习惯于
指向集合中的特定资源，例如已标识的项目
通过ID。一个URL可以有几个路径参数，每个参数用花括号表示
{ }.
/v2/projects/{projectId}
路径参数 是必需的 并且必须在请求中直接定义 对象。
// Setting the projectId path parameters
const project = await mittwaldApi.project.getProject({
projectId: "p-xxxxx",
});
报头、查询参数和请求正文
根据不同的操作，还需要配置额外的参数，例如
queryParameters （URL查询参数）， headers （HTTP报头），以及 data
(请求主体)。
操作及其参数记录在 API文档.
当使用TypeScript时，所有的参数模式都由请求类型反映， 因此，当请求与模式不匹配时，您将获得编译错误。
const response = await mittwaldApi.category.operation({
// path parameters
pathParameter1: "param1",
pathParameter2: "param2",
// parameters in header
headers: {
"x-header": "header",
},
// query parameters
queryParameters: {
queryParameter1: "queryParam1",
queryParameter2: "queryParam2",
},
// JSON object in request body
data: {
data1: "data1",
data2: "data2",
},
});
日期和时间值
只要API需要日期和时间（API中的ISO 8601字符串）
文档)，您可以自己传递该字符串，也可以简单地传递
JavaScript Date. Date 值被转换成ISO 8601格式
发送-在请求体（在任何嵌套深度），在查询参数，路径
参数和头文件。
await mittwaldApi.contract.terminateContractItem({
contractId: "contract-id",
contractItemId: "contract-item-id",
data: {
terminationTargetDate: new Date("2024-12-10"),
},
});
注意，这适用于 date-time 只值。只值
（YYYY-MM-DD)仍然需要作为字符串传递，并且响应总是包含
字符串,从来没有 Date 对象。
例子
import { MittwaldAPIV2Client } from "@mittwald/api-client";
const mittwaldApi = MittwaldAPIClient.newWithToken("your-access-token");
const projects = await mittwaldApi.project.listProjects();
React中的用法
这个包还提供了一个在React组件中使用的客户端。它
使用
@mittwald/react-use-promise
将异步API函数封装到AsyncResources中。更多的细节
关于如何使用AsyncResources，请参阅
包的文档.
安装
要使用React客户端，您必须安装附加的
@mittwald/react-use-promise 包:
yarn add @mittwald/react-use-promise
设置
要创建一个React客户端实例，首先需要一个regular的实例
(当)客户机。然后你可以使用 .fromBaseClient(api) 方法
构建React客户端。
const api = MittwaldAPIV2Client.newUnauthenticated();
const apiReact = MittwaldAPIV2ClientReact.fromBaseClient(api);
使用
React客户端对常规客户端的每个GET方法都有一个等价的GET方法。 返回可用于获取API的AsyncResource的方法 响应。
如果响应不是OK（状态200），则 ApiClientError 会被扔。
错误可以通过使用错误边界来处理。看到
错误处理部分
了解更多详情。
例子
import { MittwaldAPIV2Client } from "@mittwald/api-client";
import { MittwaldAPIV2ClientReact } from "@mittwald/api-client/react";
const api = MittwaldAPIV2Client.newUnauthenticated();
const apiReact = MittwaldAPIV2ClientReact.fromBaseClient(api);
const ProjectsList = () => {
// apiReact.project.listProjects() returns an AsyncResource that can be "used"
const projects = apiReact.project.listProjects().use({
autoRefresh: {
seconds: 30,
},
});
return (
<ul>
{projects.map((p) => (
<li key={p.id}>{p.description}</li>
))}
</ul>
);
};
API文档
API文档可以在 https://api.mittwald.de/v2/docs/． 你可以 在每个操作的右侧找到操作ID。
访问底层Axios实例
客户端使用流行的 Axios HTTP客户端 下
罩。您可以使用客户机访问Axios实例 axios 财产。
添加自定义HTTP标头
要向所有请求添加自定义HTTP头，您可以使用Axios的 defaults.headers
属性:
client.axios.defaults.headers["User-Agent"] = `your-tool/v1.2.3`;
拦截请求或响应
来拦截请求或响应，您可以使用 Axios的拦截器.
TypeScript的用法
中导入所有响应和请求类型 MittwaldAPIV2
名称空间。
引用请求/响应类型
import { MittwaldAPIV2 } from "@mittwald/api-client";
type ProjectData = MittwaldAPIV2.Operations.ProjectGetProject.ResponseData;
// Reference "non-200" response type
type ProjectNotFoundData =
MittwaldAPIV2.Operations.ProjectGetProject.ResponseData<404>;
type CreateProjectData =
MittwaldAPIV2.Operations.ProjectCreateProject.RequestData;
从包版本V2迁移到V3
此指令考虑从 包 version V2到V3 在请求调用的呼叫签名中有重大更改。API本身有 没有改变，仍然是版本2。
路径参数是请求的主要组成部分，因此不应该是 “隐藏”在请求配置对象中。在V3中，请求的API 配置对象发生变化，需要重新设置路径参数 直接在请求对象的根级别。
// V2
mittwaldApi.project.getProject({
pathParameters: {
projectId: "p-xxxxx",
},
});
// V3
mittwaldApi.project.getProject({
projectId: "p-xxxxx",
});