OpenAPI

API 由一份 OpenAPI 文档描述：其中包含每个操作、它接受什么以及返回什么，并附有说明。可从以下地址获取：

https://saas.parametriq.co.uk/openapi.json

获取该文档本身无需 API 密钥，只有调用其描述的操作时才需要。它采用 OpenAPI 3.1，并将 https://saas.parametriq.co.uk 指定为服务器，因此由它生成的客户端会调用该地址上的服务。其安全方案 ApiKey 即为 X-API-KEY 标头中的密钥（使用 API 密钥）。

它可用于：

• 生成客户端：用您自己的语言生成，每个请求和响应各对应一个类，每个操作各对应一个方法（见下文）；
• 试用 API：在可读取 OpenAPI 文档的工具（如 Postman、Insomnia、Bruno 或 Swagger UI）中导入上述地址，设置 X-API-KEY 标头，然后发送请求；
• 查看 API 接受的内容：该文档是完整的参考，而 API 页面则是它的指南。

使用 Kiota 生成客户端

Kiota 是 Microsoft 的客户端生成器。它可以根据 OpenAPI 文档生成 C#、Go、Java、PHP、Python、Ruby 和 TypeScript 客户端。以 C# 为例：

dotnet tool install --global Microsoft.OpenApi.Kiota
dotnet new console -n PiqDemo
cd PiqDemo
dotnet add package Microsoft.Kiota.Bundle
kiota generate -l CSharp -c PiqClient -n Piq.Client -d https://saas.parametriq.co.uk/openapi.json -o ./Client

这会在 Client 文件夹中生成一个 PiqClient 类，其中每个操作各有一个请求构建器（client.Inputs、 client.Measure、client.Export["pdf"] …），每个请求和响应各有一个类（TemplateRequest、 DrawingRequest、MeasureResponse …）。然后：

using Microsoft.Kiota.Abstractions.Authentication;
using Microsoft.Kiota.Abstractions.Serialization;
using Microsoft.Kiota.Http.HttpClientLibrary;
using Piq.Client;
using Piq.Client.Models;

// the key goes in the X-API-KEY header of every request
var key = Environment.GetEnvironmentVariable("PIQ_API_KEY") ?? throw new InvalidOperationException("Set PIQ_API_KEY.");
var auth = new ApiKeyAuthenticationProvider(key, "X-API-KEY", ApiKeyAuthenticationProvider.KeyLocation.Header);
var adapter = new HttpClientRequestAdapter(auth);
if (Environment.GetEnvironmentVariable("PIQ_URL") is { } url) adapter.BaseUrl = url;
var client = new PiqClient(adapter);

const string template = "L=400,\"Length\"\nW=300,\"Width\"\nP1=[L,0]\nP2=[L,W]\nP3=[0,W]\nPOLYLINE @1,[P0,P1,P2,P3],TRUE,0";

// the template's labelled variables
var inputs = await client.Inputs.PostAsync(new TemplateRequest { Template = template });
foreach (var input in inputs!.Inputs!) Console.WriteLine($"{input.Name}: {input.Label} ({input.Kind})");

// values for them: any of the template's labelled variables, by name
var values = new DrawingRequest_values { AdditionalData = { ["L"] = 500, ["W"] = 250 } };

// measured
var measured = await client.Measure.PostAsync(new DrawingRequest { Template = template, Values = values });
Console.WriteLine($"Size: {measured!.Width} x {measured.Height}");

// exported as a PDF
var pdf = await client.Export["pdf"].PostAsync(new ExportRequest
{
    Template = template, Values = new ExportRequest_values { AdditionalData = values.AdditionalData }
});
await using (var file = File.Create("box.pdf")) await pdf!.CopyToAsync(file);
Console.WriteLine("Saved box.pdf");

// a value that can't be used: refused, saying why
try
{
    await client.Measure.PostAsync(new DrawingRequest
    {
        Template = template, Values = new DrawingRequest_values { AdditionalData = { ["L"] = "long" } }
    });
}
catch (ValidationProblemDetails problem)
{
    Console.WriteLine($"{problem.Title} {problem.Detail}");
    // what is wrong, by the value it is about: each a list of messages
    foreach (var (name, messages) in problem.Errors?.AdditionalData ?? new Dictionary<string, object>())
        if (messages is UntypedArray list)
            Console.WriteLine($"  {name}: {string.Join(" ", list.GetValue().OfType<UntypedString>().Select(m => m.GetValue()))}");
}

工作原理：

• 密钥。 ApiKeyAuthenticationProvider 会把您的密钥放入每个请求的 X-API-KEY 标头中（仅限 https）。
• 值。 模板中带标签的变量由模板自身决定，因此 values 没有固定字段：请在 AdditionalData 中按名称给出。
• 文件。 Export（以及 Preview）返回一个 Stream：即文件的字节，无论其格式如何。
• 错误。 被拒绝的请求会抛出问题描述：ValidationProblemDetails（400），其 Errors 中说明哪个值有什么问题；其他情况则为 ProblemDetails（404、409、422、502 …）。

API 发生变化时，请再次运行 kiota generate，使客户端保持最新。如需其他语言，请用 -l 指定其名称（Go、Java、PHP、Python、Ruby、TypeScript），并添加该语言的 Kiota 包， kiota info -l <language> 会列出这些包。

其他生成器

任何 OpenAPI 生成器都可以使用同一地址：

• NSwag（C# 和 TypeScript）：nswag openapi2csclient /input:https://saas.parametriq.co.uk/openapi.json /output:PiqClient.cs /namespace:Piq.Client。
• OpenAPI Generator（大多数语言）： npx @openapitools/openapi-generator-cli generate -i https://saas.parametriq.co.uk/openapi.json -g python -o piq-client，其中 -g 指定语言（typescript-fetch、java、go、php、ruby、csharp …）。

与所有请求一样，生成的客户端需要在 X-API-KEY 标头中提供您的密钥：每种生成器都有自己的提供方式（API 密钥设置或默认标头）。

如果您不想生成任何代码，API 使用的是普通的 HTTPS 和 JSON：请参阅客户端，其中提供了多种语言的完整示例，仅使用各语言自带的 HTTP 客户端。

另请参阅：API、客户端、使用 API 密钥。