hanzoai/docs
2
0
Fork 0
mirror of https://github.com/hanzo-docs/docs.git synced 2026-10-25 04:20:02 +00:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

OpenAPI: Display object types mentioned in schema

Browse Source
This commit is contained in:
fuma-nama
2024-07-08 15:22:11 +08:00
parent 6e9d4bfd9d
commit b1b154e47f
11 changed files with 482 additions and 205 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.changeset/chilled-peas-play.md
+5
View File
@@ -0,0 +1,5 @@
---
'fumadocs-openapi': minor
---
Display object types mentioned in schema
packages/openapi/src/render/schema.ts
+56 -39
View File
@@ -44,32 +44,31 @@ export function schemaElement(
const child: string[] = [];
function field(key: string, value: string): void {
child.push(span(`${key}: \`${value}\``));
child.push(span(`${key}: \`${value}\``));
}
// object type
if (isObject(schema) && ctx.parseObject) {
const { additionalProperties, properties } = schema;
if (additionalProperties) {
if (additionalProperties === true) {
child.push(
renderer.Property(
{
name: '[key: string]',
type: 'any',
},
[],
),
);
} else {
child.push(
schemaElement('[key: string]', noRef(additionalProperties), {
...ctx,
required: false,
parseObject: false,
}),
);
}
if (additionalProperties === true) {
child.push(
renderer.Property(
{
name: '[key: string]',
type: 'any',
},
[],
),
);
} else if (additionalProperties) {
child.push(
schemaElement('[key: string]', noRef(additionalProperties), {
...ctx,
required: false,
parseObject: false,
}),
);
}
Object.entries(properties ?? {}).forEach(([key, value]) => {
@@ -92,6 +91,7 @@ export function schemaElement(
}
}
// enum types
if (schema.enum) {
field(
'Value in',
@@ -99,12 +99,32 @@ export function schemaElement(
);
}
const resolved = resolveObjectType(schema);
const mentionedObjectTypes = [
...(schema.anyOf ?? schema.oneOf ?? schema.allOf ?? []),
...(schema.type === 'array' ? [schema.items] : []),
]
.map(noRef)
.filter((s) => isObject(s));
if (resolved && !ctx.parseObject) {
child.push(
...mentionedObjectTypes.map((s, idx) =>
renderer.ObjectCollapsible(
{ name: s.title ?? `Object ${(idx + 1).toString()}` },
[
schemaElement('element', noRef(s), {
...ctx,
parseObject: true,
required: false,
}),
],
),
),
);
if (isObject(schema) && !ctx.parseObject) {
child.push(
renderer.ObjectCollapsible({ name }, [
schemaElement(name, resolved, {
schemaElement(name, schema, {
...ctx,
parseObject: true,
required: false,
@@ -124,21 +144,14 @@ export function schemaElement(
);
}
function resolveObjectType(
schema: OpenAPI.SchemaObject,
): OpenAPI.SchemaObject | undefined {
if (isObject(schema)) return schema;
if (schema.type === 'array') {
return resolveObjectType(noRef(schema.items));
}
}
function getSchemaType(schema: OpenAPI.SchemaObject): string {
if (schema.nullable) {
if (!schema.type) return 'null';
if (schema.title) return schema.title;
return `${getSchemaType({ ...schema, nullable: false })} | null`;
if (schema.nullable) {
const type = getSchemaType({ ...schema, nullable: false });
// null if schema only contains `nullable`
return type === 'unknown' ? 'null' : `${type} | null`;
}
if (schema.type === 'array')
@@ -150,14 +163,18 @@ function getSchemaType(schema: OpenAPI.SchemaObject): string {
if (schema.allOf)
return schema.allOf.map((one) => getSchemaType(noRef(one))).join(' & ');
if (schema.anyOf)
if (schema.not) return `not ${getSchemaType(noRef(schema.not))}`;
if (schema.anyOf) {
return `Any properties in ${schema.anyOf
.map((one) => getSchemaType(noRef(one)))
.join(', ')}`;
}
if (schema.type) return schema.type;
// object without specified type
if (isObject(schema)) return 'object';
throw new Error(`Cannot detect object type: ${JSON.stringify(schema)}`);
return 'unknown';
}
packages/openapi/test/out/museum/events.mdx
+25 -25
View File
@@ -30,9 +30,9 @@ In: `header`
The starting date to retrieve future operating hours from. Defaults to today's date.
<span>Example: `"2023-02-23"`</span>
<span>Example: `"2023-02-23"`</span>
<span>Format: `"date"`</span>
<span>Format: `"date"`</span>
</Property>
@@ -40,9 +40,9 @@ The starting date to retrieve future operating hours from. Defaults to today's d
The end of a date range to retrieve special events for. Defaults to 7 days after `startDate`.
<span>Example: `"2023-04-18"`</span>
<span>Example: `"2023-04-18"`</span>
<span>Format: `"date"`</span>
<span>Format: `"date"`</span>
</Property>
@@ -50,9 +50,9 @@ The end of a date range to retrieve special events for. Defaults to 7 days after
The page number to retrieve.
<span>Example: `2`</span>
<span>Example: `2`</span>
<span>Default: `1`</span>
<span>Default: `1`</span>
</Property>
@@ -60,11 +60,11 @@ The page number to retrieve.
The number of days per page.
<span>Example: `15`</span>
<span>Example: `15`</span>
<span>Default: `10`</span>
<span>Default: `10`</span>
<span>Maximum: `30`</span>
<span>Maximum: `30`</span>
</Property>
@@ -195,7 +195,7 @@ In: `header`
Name of the special event
<span>Example: `"Pirate Coding Workshop"`</span>
<span>Example: `"Pirate Coding Workshop"`</span>
</Property>
@@ -203,7 +203,7 @@ Name of the special event
Location where the special event is held
<span>Example: `"Computer Room"`</span>
<span>Example: `"Computer Room"`</span>
</Property>
@@ -211,7 +211,7 @@ Location where the special event is held
Description of the special event
<span>Example: `"Captain Blackbeard shares his love of the C...language. And possibly Arrrrr (R lang)."`</span>
<span>Example: `"Captain Blackbeard shares his love of the C...language. And possibly Arrrrr (R lang)."`</span>
</Property>
@@ -225,9 +225,9 @@ List of planned dates for the special event
Price of a ticket for the special event
<span>Example: `25`</span>
<span>Example: `25`</span>
<span>Format: `"float"`</span>
<span>Format: `"float"`</span>
</Property>
@@ -365,9 +365,9 @@ In: `header`
An identifier for a special event.
<span>Example: `"dad4bce8-f5cb-4078-a211-995864315e39"`</span>
<span>Example: `"dad4bce8-f5cb-4078-a211-995864315e39"`</span>
<span>Format: `"uuid"`</span>
<span>Format: `"uuid"`</span>
</Property>
@@ -496,7 +496,7 @@ In: `header`
Name of the special event
<span>Example: `"Pirate Coding Workshop"`</span>
<span>Example: `"Pirate Coding Workshop"`</span>
</Property>
@@ -504,7 +504,7 @@ Name of the special event
Location where the special event is held
<span>Example: `"Computer Room"`</span>
<span>Example: `"Computer Room"`</span>
</Property>
@@ -512,7 +512,7 @@ Location where the special event is held
Description of the special event
<span>Example: `"Captain Blackbeard shares his love of the C...language. And possibly Arrrrr (R lang)."`</span>
<span>Example: `"Captain Blackbeard shares his love of the C...language. And possibly Arrrrr (R lang)."`</span>
</Property>
@@ -526,9 +526,9 @@ List of planned dates for the special event
Price of a ticket for the special event
<span>Example: `25`</span>
<span>Example: `25`</span>
<span>Format: `"float"`</span>
<span>Format: `"float"`</span>
</Property>
@@ -538,9 +538,9 @@ Price of a ticket for the special event
An identifier for a special event.
<span>Example: `"dad4bce8-f5cb-4078-a211-995864315e39"`</span>
<span>Example: `"dad4bce8-f5cb-4078-a211-995864315e39"`</span>
<span>Format: `"uuid"`</span>
<span>Format: `"uuid"`</span>
</Property>
@@ -678,9 +678,9 @@ In: `header`
An identifier for a special event.
<span>Example: `"dad4bce8-f5cb-4078-a211-995864315e39"`</span>
<span>Example: `"dad4bce8-f5cb-4078-a211-995864315e39"`</span>
<span>Format: `"uuid"`</span>
<span>Format: `"uuid"`</span>
</Property>
packages/openapi/test/out/museum/operations.mdx
+7 -7
View File
@@ -30,9 +30,9 @@ In: `header`
The starting date to retrieve future operating hours from. Defaults to today's date.
<span>Example: `"2023-02-23"`</span>
<span>Example: `"2023-02-23"`</span>
<span>Format: `"date"`</span>
<span>Format: `"date"`</span>
</Property>
@@ -40,9 +40,9 @@ The starting date to retrieve future operating hours from. Defaults to today's d
The page number to retrieve.
<span>Example: `2`</span>
<span>Example: `2`</span>
<span>Default: `1`</span>
<span>Default: `1`</span>
</Property>
@@ -50,11 +50,11 @@ The page number to retrieve.
The number of days per page.
<span>Example: `15`</span>
<span>Example: `15`</span>
<span>Default: `10`</span>
<span>Default: `10`</span>
<span>Maximum: `30`</span>
<span>Maximum: `30`</span>
</Property>
packages/openapi/test/out/museum/tickets.mdx
+11 -11
View File
@@ -30,9 +30,9 @@ In: `header`
Type of ticket being purchased. Use `general` for regular museum entry and `event` for tickets to special events.
<span>Example: `"event"`</span>
<span>Example: `"event"`</span>
<span>Value in: `"event" | "general"`</span>
<span>Value in: `"event" | "general"`</span>
</Property>
@@ -40,9 +40,9 @@ Type of ticket being purchased. Use `general` for regular museum entry and `even
Identifier for a special event.
<span>Example: `"3be6453c-03eb-4357-ae5a-984a0e574a54"`</span>
<span>Example: `"3be6453c-03eb-4357-ae5a-984a0e574a54"`</span>
<span>Format: `"uuid"`</span>
<span>Format: `"uuid"`</span>
</Property>
@@ -50,9 +50,9 @@ Identifier for a special event.
Date that the ticket is valid for.
<span>Example: `"2023-10-29"`</span>
<span>Example: `"2023-10-29"`</span>
<span>Format: `"date"`</span>
<span>Format: `"date"`</span>
</Property>
@@ -60,9 +60,9 @@ Date that the ticket is valid for.
Email address for ticket purchaser.
<span>Example: `"[email protected]"`</span>
<span>Example: `"[email protected]"`</span>
<span>Format: `"email"`</span>
<span>Format: `"email"`</span>
</Property>
@@ -70,7 +70,7 @@ Email address for ticket purchaser.
Phone number for the ticket purchaser (optional).
<span>Example: `"+1(234)-567-8910"`</span>
<span>Example: `"+1(234)-567-8910"`</span>
</Property>
@@ -204,9 +204,9 @@ In: `header`
An identifier for a ticket to a museum event. Used to generate ticket image.
<span>Example: `"a54a57ca-36f8-421b-a6b4-2e8f26858a4c"`</span>
<span>Example: `"a54a57ca-36f8-421b-a6b4-2e8f26858a4c"`</span>
<span>Format: `"uuid"`</span>
<span>Format: `"uuid"`</span>
</Property>
packages/openapi/test/out/petstore.mdx
+3 -3
View File
@@ -19,9 +19,9 @@ import { Root, API, APIInfo, APIExample, Responses, Response, ResponseTypes, Exa
How many items to return at one time (max 100)
<span>Maximum: `100`</span>
<span>Maximum: `100`</span>
<span>Format: `"int32"`</span>
<span>Format: `"int32"`</span>
</Property>
@@ -141,7 +141,7 @@ export interface Response {
<Property name={"id"} type={"integer"} required={true} deprecated={undefined}>
<span>Format: `"int64"`</span>
<span>Format: `"int64"`</span>
</Property>
packages/openapi/test/out/unkey/apis.mdx
+12 -12
View File
@@ -27,9 +27,9 @@ In: `header`
The id of the api to fetch
<span>Example: `"api_1234"`</span>
<span>Example: `"api_1234"`</span>
<span>Minimum length: `1`</span>
<span>Minimum length: `1`</span>
</Property>
@@ -489,9 +489,9 @@ In: `header`
The id of the api to fetch
<span>Example: `"api_1234"`</span>
<span>Example: `"api_1234"`</span>
<span>Minimum length: `1`</span>
<span>Minimum length: `1`</span>
</Property>
@@ -499,13 +499,13 @@ The id of the api to fetch
The maximum number of keys to return
<span>Example: `100`</span>
<span>Example: `100`</span>
<span>Default: `100`</span>
<span>Default: `100`</span>
<span>Minimum: `1`</span>
<span>Minimum: `1`</span>
<span>Maximum: `100`</span>
<span>Maximum: `100`</span>
</Property>
@@ -519,7 +519,7 @@ Use this to fetch the next page of results. A new cursor will be returned in the
If provided, this will only return keys where the `ownerId` matches.
<span>Minimum length: `1`</span>
<span>Minimum length: `1`</span>
</Property>
@@ -1134,9 +1134,9 @@ In: `header`
The id of the api, that the keys belong to.
<span>Example: `"api_1234"`</span>
<span>Example: `"api_1234"`</span>
<span>Minimum length: `1`</span>
<span>Minimum length: `1`</span>
</Property>
@@ -1144,7 +1144,7 @@ The id of the api, that the keys belong to.
If true, the keys will be permanently deleted. If false, the keys will be soft-deleted and can be restored later.
<span>Default: `false`</span>
<span>Default: `false`</span>
</Property>
packages/openapi/test/out/unkey/keys.mdx
+80 -64
View File
@@ -27,9 +27,9 @@ In: `header`
The id of the key to fetch
<span>Example: `"key_1234"`</span>
<span>Example: `"key_1234"`</span>
<span>Minimum length: `1`</span>
<span>Minimum length: `1`</span>
</Property>
@@ -628,9 +628,9 @@ In: `header`
The id of the key to revoke
<span>Example: `"key_1234"`</span>
<span>Example: `"key_1234"`</span>
<span>Minimum length: `1`</span>
<span>Minimum length: `1`</span>
</Property>
@@ -1076,7 +1076,7 @@ In: `header`
Choose an `API` where this key should be created.
<span>Example: `"api_123"`</span>
<span>Example: `"api_123"`</span>
</Property>
@@ -1089,7 +1089,7 @@ For example Stripe famously prefixes their customer ids with cus_ or their api k
The underscore is automatically added if you are defining a prefix, for example: "prefix": "abc" will result in a key like abc_xxxxxxxxx
<span>Maximum length: `16`</span>
<span>Maximum length: `16`</span>
</Property>
@@ -1097,7 +1097,7 @@ The underscore is automatically added if you are defining a prefix, for example:
The name for your Key. This is not customer facing.
<span>Example: `"my key"`</span>
<span>Example: `"my key"`</span>
</Property>
@@ -1105,11 +1105,11 @@ The name for your Key. This is not customer facing.
The byte length used to generate your key determines its entropy as well as its length. Higher is better, but keys become longer and more annoying to handle. The default is 16 bytes, or 2^^128 possible combinations.
<span>Default: `16`</span>
<span>Default: `16`</span>
<span>Minimum: `16`</span>
<span>Minimum: `16`</span>
<span>Maximum: `255`</span>
<span>Maximum: `255`</span>
</Property>
@@ -1118,7 +1118,7 @@ The byte length used to generate your key determines its entropy as well as its
Your user’s Id. This will provide a link between Unkey and your customer record.
When validating a key, we will return this back to you, so you can clearly identify your user from their api key.
<span>Example: `"team_123"`</span>
<span>Example: `"team_123"`</span>
</Property>
@@ -1126,7 +1126,7 @@ When validating a key, we will return this back to you, so you can clearly ident
This is a place for dynamic meta data, anything that feels useful for you should go here
<span>Example: `{"billingTier":"PRO","trialEnds":"2023-06-16T17:16:37.161Z"}`</span>
<span>Example: `{"billingTier":"PRO","trialEnds":"2023-06-16T17:16:37.161Z"}`</span>
<ObjectCollapsible name={"meta"}>
@@ -1142,7 +1142,7 @@ This is a place for dynamic meta data, anything that feels useful for you should
A list of roles that this key should have. If the role does not exist, an error is thrown
<span>Example: `["admin","finance"]`</span>
<span>Example: `["admin","finance"]`</span>
</Property>
@@ -1150,7 +1150,7 @@ A list of roles that this key should have. If the role does not exist, an error
A list of permissions that this key should have. If the permission does not exist, an error is thrown
<span>Example: `["domains.create_record","say_hello"]`</span>
<span>Example: `["domains.create_record","say_hello"]`</span>
</Property>
@@ -1158,7 +1158,7 @@ A list of permissions that this key should have. If the permission does not exis
You can auto expire keys by providing a unix timestamp in milliseconds. Once Keys expire they will automatically be disabled and are no longer valid unless you enable them again.
<span>Example: `1623869797161`</span>
<span>Example: `1623869797161`</span>
</Property>
@@ -1166,7 +1166,7 @@ You can auto expire keys by providing a unix timestamp in milliseconds. Once Key
You can limit the number of requests a key can make. Once a key reaches 0 remaining requests, it will automatically be disabled and is no longer valid unless you update it.
<span>Example: `1000`</span>
<span>Example: `1000`</span>
</Property>
@@ -1174,7 +1174,7 @@ You can limit the number of requests a key can make. Once a key reaches 0 remain
Unkey enables you to refill verifications for each key at regular intervals.
<span>Example: `{"interval":"daily","amount":100}`</span>
<span>Example: `{"interval":"daily","amount":100}`</span>
<ObjectCollapsible name={"refill"}>
@@ -1182,7 +1182,7 @@ Unkey enables you to refill verifications for each key at regular intervals.
Unkey will automatically refill verifications at the set interval.
<span>Value in: `"daily" | "monthly"`</span>
<span>Value in: `"daily" | "monthly"`</span>
</Property>
@@ -1190,7 +1190,7 @@ Unkey will automatically refill verifications at the set interval.
The number of verifications to refill for each occurrence is determined individually for each key.
<span>Minimum: `0`</span>
<span>Minimum: `0`</span>
</Property>
@@ -1202,7 +1202,7 @@ The number of verifications to refill for each occurrence is determined individu
Unkey comes with per-key fixed-window ratelimiting out of the box.
<span>Example: `{"type":"fast","limit":10,"duration":60000}`</span>
<span>Example: `{"type":"fast","limit":10,"duration":60000}`</span>
<ObjectCollapsible name={"ratelimit"}>
@@ -1210,7 +1210,7 @@ Unkey comes with per-key fixed-window ratelimiting out of the box.
Async will return a response immediately, lowering latency at the cost of accuracy. Will be required soon.
<span>Default: `true`</span>
<span>Default: `true`</span>
</Property>
@@ -1218,9 +1218,9 @@ Async will return a response immediately, lowering latency at the cost of accura
Deprecated, used `async`. Fast ratelimiting doesn't add latency, while consistent ratelimiting is more accurate.
<span>Default: `"fast"`</span>
<span>Default: `"fast"`</span>
<span>Value in: `"fast" | "consistent"`</span>
<span>Value in: `"fast" | "consistent"`</span>
</Property>
@@ -1228,7 +1228,7 @@ Deprecated, used `async`. Fast ratelimiting doesn't add latency, while consisten
The total amount of requests in a given interval.
<span>Minimum: `1`</span>
<span>Minimum: `1`</span>
</Property>
@@ -1236,9 +1236,9 @@ The total amount of requests in a given interval.
The window duration in milliseconds. Will be required soon.
<span>Example: `60000`</span>
<span>Example: `60000`</span>
<span>Minimum: `1000`</span>
<span>Minimum: `1000`</span>
</Property>
@@ -1246,7 +1246,7 @@ The window duration in milliseconds. Will be required soon.
How many tokens to refill during each refillInterval.
<span>Minimum: `1`</span>
<span>Minimum: `1`</span>
</Property>
@@ -1254,7 +1254,7 @@ How many tokens to refill during each refillInterval.
The refill timeframe, in milliseconds.
<span>Minimum: `1`</span>
<span>Minimum: `1`</span>
</Property>
@@ -1266,9 +1266,9 @@ The refill timeframe, in milliseconds.
Sets if key is enabled or disabled. Disabled keys are not valid.
<span>Example: `false`</span>
<span>Example: `false`</span>
<span>Default: `true`</span>
<span>Default: `true`</span>
</Property>
@@ -1284,7 +1284,7 @@ When you set an environment, we will return it back to you when validating the k
handle it correctly.
<span>Maximum length: `256`</span>
<span>Maximum length: `256`</span>
</Property>
@@ -1764,7 +1764,7 @@ export interface Response {
The id of the api where the key belongs to. This is optional for now but will be required soon.
The key will be verified against the api's configuration. If the key does not belong to the api, the verification will fail.
<span>Example: `"api_1234"`</span>
<span>Example: `"api_1234"`</span>
</Property>
@@ -1772,9 +1772,9 @@ The key will be verified against the api's configuration. If the key does not be
The key to verify
<span>Example: `"sk_1234"`</span>
<span>Example: `"sk_1234"`</span>
<span>Minimum length: `1`</span>
<span>Minimum length: `1`</span>
</Property>
@@ -1784,10 +1784,26 @@ Perform RBAC checks
<ObjectCollapsible name={"authorization"}>
<Property name={"permissions"} type={"null"} required={false} deprecated={undefined}>
<Property name={"permissions"} type={"LiteralClause | And | Or | null"} required={false} deprecated={undefined}>
A query for which permissions you require
<ObjectCollapsible name={"And"}>
<Property name={"and"} type={"array of LiteralClause | And | Or | null"} required={true} deprecated={undefined}>
</Property>
</ObjectCollapsible>
<ObjectCollapsible name={"Or"}>
<Property name={"or"} type={"array of LiteralClause | And | Or | null"} required={true} deprecated={undefined}>
</Property>
</ObjectCollapsible>
</Property>
</ObjectCollapsible>
@@ -1802,9 +1818,9 @@ A query for which permissions you require
Override how many tokens are deducted during the ratelimit operation.
<span>Default: `1`</span>
<span>Default: `1`</span>
<span>Minimum: `0`</span>
<span>Minimum: `0`</span>
</Property>
@@ -2372,7 +2388,7 @@ In: `header`
The id of the key you want to modify
<span>Example: `"key_123"`</span>
<span>Example: `"key_123"`</span>
</Property>
@@ -2380,7 +2396,7 @@ The id of the key you want to modify
The name of the key
<span>Example: `"Customer X"`</span>
<span>Example: `"Customer X"`</span>
</Property>
@@ -2388,7 +2404,7 @@ The name of the key
The id of the tenant associated with this key. Use whatever reference you have in your system to identify the tenant. When verifying the key, we will send this field back to you, so you know who is accessing your API.
<span>Example: `"user_123"`</span>
<span>Example: `"user_123"`</span>
</Property>
@@ -2396,7 +2412,7 @@ The id of the tenant associated with this key. Use whatever reference you have i
Any additional metadata you want to store with the key
<span>Example: `{"roles":["admin","user"],"stripeCustomerId":"cus_1234"}`</span>
<span>Example: `{"roles":["admin","user"],"stripeCustomerId":"cus_1234"}`</span>
<ObjectCollapsible name={"meta"}>
@@ -2412,7 +2428,7 @@ Any additional metadata you want to store with the key
The unix timestamp in milliseconds when the key will expire. If this field is null or undefined, the key is not expiring.
<span>Example: `0`</span>
<span>Example: `0`</span>
</Property>
@@ -2420,7 +2436,7 @@ The unix timestamp in milliseconds when the key will expire. If this field is nu
Unkey comes with per-key ratelimiting out of the box. Set `null` to disable.
<span>Example: `{"type":"fast","limit":10,"refillRate":1,"refillInterval":60}`</span>
<span>Example: `{"type":"fast","limit":10,"refillRate":1,"refillInterval":60}`</span>
<ObjectCollapsible name={"ratelimit"}>
@@ -2428,7 +2444,7 @@ Unkey comes with per-key ratelimiting out of the box. Set `null` to disable.
Fast ratelimiting doesn't add latency, while consistent ratelimiting is more accurate.
<span>Value in: `"fast" | "consistent"`</span>
<span>Value in: `"fast" | "consistent"`</span>
</Property>
@@ -2436,7 +2452,7 @@ Fast ratelimiting doesn't add latency, while consistent ratelimiting is more acc
Asnyc ratelimiting doesn't add latency, while sync ratelimiting is more accurate.
<span>Default: `false`</span>
<span>Default: `false`</span>
</Property>
@@ -2444,7 +2460,7 @@ Asnyc ratelimiting doesn't add latency, while sync ratelimiting is more accurate
The total amount of burstable requests.
<span>Minimum: `1`</span>
<span>Minimum: `1`</span>
</Property>
@@ -2452,7 +2468,7 @@ The total amount of burstable requests.
How many tokens to refill during each refillInterval.
<span>Minimum: `1`</span>
<span>Minimum: `1`</span>
</Property>
@@ -2460,7 +2476,7 @@ How many tokens to refill during each refillInterval.
Determines the speed at which tokens are refilled, in milliseconds.
<span>Minimum: `1`</span>
<span>Minimum: `1`</span>
</Property>
@@ -2468,7 +2484,7 @@ Determines the speed at which tokens are refilled, in milliseconds.
The duration of each ratelimit window, in milliseconds.
<span>Minimum: `1`</span>
<span>Minimum: `1`</span>
</Property>
@@ -2480,7 +2496,7 @@ The duration of each ratelimit window, in milliseconds.
The number of requests that can be made with this key before it becomes invalid. Set `null` to disable.
<span>Example: `1000`</span>
<span>Example: `1000`</span>
</Property>
@@ -2488,7 +2504,7 @@ The number of requests that can be made with this key before it becomes invalid.
Unkey enables you to refill verifications for each key at regular intervals.
<span>Example: `{"interval":"daily","amount":100}`</span>
<span>Example: `{"interval":"daily","amount":100}`</span>
<ObjectCollapsible name={"refill"}>
@@ -2496,7 +2512,7 @@ Unkey enables you to refill verifications for each key at regular intervals.
Unkey will automatically refill verifications at the set interval. If null is used the refill functionality will be removed from the key.
<span>Value in: `"daily" | "monthly"`</span>
<span>Value in: `"daily" | "monthly"`</span>
</Property>
@@ -2504,7 +2520,7 @@ Unkey will automatically refill verifications at the set interval. If null is us
The amount of verifications to refill for each occurrence is determined individually for each key.
<span>Minimum: `1`</span>
<span>Minimum: `1`</span>
</Property>
@@ -2516,7 +2532,7 @@ The amount of verifications to refill for each occurrence is determined individu
Set if key is enabled or disabled. If disabled, the key cannot be used to verify.
<span>Example: `true`</span>
<span>Example: `true`</span>
</Property>
@@ -2984,7 +3000,7 @@ In: `header`
The id of the key you want to modify
<span>Example: `"key_123"`</span>
<span>Example: `"key_123"`</span>
</Property>
@@ -2992,7 +3008,7 @@ The id of the key you want to modify
The operation you want to perform on the remaining count
<span>Value in: `"increment" | "decrement" | "set"`</span>
<span>Value in: `"increment" | "decrement" | "set"`</span>
</Property>
@@ -3000,7 +3016,7 @@ The operation you want to perform on the remaining count
The value you want to set, add or subtract the remaining count by
<span>Example: `1`</span>
<span>Example: `1`</span>
</Property>
@@ -3455,7 +3471,7 @@ In: `header`
The id of the key to fetch, either `keyId` or `ownerId` must be provided
<span>Example: `"key_1234"`</span>
<span>Example: `"key_1234"`</span>
</Property>
@@ -3463,7 +3479,7 @@ The id of the key to fetch, either `keyId` or `ownerId` must be provided
The owner id to fetch keys for, either `keyId` or `ownerId` must be provided
<span>Example: `"chronark"`</span>
<span>Example: `"chronark"`</span>
</Property>
@@ -3471,7 +3487,7 @@ The owner id to fetch keys for, either `keyId` or `ownerId` must be provided
The start of the period to fetch usage for as unix milliseconds timestamp
<span>Example: `1620000000000`</span>
<span>Example: `1620000000000`</span>
</Property>
@@ -3479,7 +3495,7 @@ The start of the period to fetch usage for as unix milliseconds timestamp
The end of the period to fetch usage for as unix milliseconds timestamp
<span>Example: `1620000000000`</span>
<span>Example: `1620000000000`</span>
</Property>
@@ -3487,11 +3503,11 @@ The end of the period to fetch usage for as unix milliseconds timestamp
The granularity of the usage data to fetch, currently only `day` is supported
<span>Example: `"day"`</span>
<span>Example: `"day"`</span>
<span>Default: `"day"`</span>
<span>Default: `"day"`</span>
<span>Value in: `"day"`</span>
<span>Value in: `"day"`</span>
</Property>
packages/openapi/test/out/unkey/migrations.mdx
+265 -27
View File
@@ -25,6 +25,244 @@ In: `header`
<Property name={"body"} type={"array of object"} required={true} deprecated={undefined}>
<ObjectCollapsible name={"Object 1"}>
<Property name={"apiId"} type={"string"} required={true} deprecated={undefined}>
Choose an `API` where this key should be created.
<span>Example: `"api_123"`</span>
</Property>
<Property name={"prefix"} type={"string"} required={false} deprecated={undefined}>
To make it easier for your users to understand which product an api key belongs to, you can add prefix them.
For example Stripe famously prefixes their customer ids with cus_ or their api keys with sk_live_.
The underscore is automatically added if you are defining a prefix, for example: "prefix": "abc" will result in a key like abc_xxxxxxxxx
<span>Maximum length: `8`</span>
</Property>
<Property name={"name"} type={"string"} required={false} deprecated={undefined}>
The name for your Key. This is not customer facing.
<span>Example: `"my key"`</span>
</Property>
<Property name={"plaintext"} type={"string"} required={false} deprecated={undefined}>
The raw key in plaintext. If provided, unkey encrypts this value and stores it securely. Provide either `hash` or `plaintext`
</Property>
<Property name={"hash"} type={"object"} required={false} deprecated={undefined}>
Provide either `hash` or `plaintext`
<ObjectCollapsible name={"hash"}>
<Property name={"value"} type={"string"} required={true} deprecated={undefined}>
The hashed and encoded key
</Property>
<Property name={"variant"} type={"string"} required={true} deprecated={undefined}>
The algorithm for hashing and encoding, currently only sha256 and base64 are supported
<span>Value in: `"sha256_base64"`</span>
</Property>
</ObjectCollapsible>
</Property>
<Property name={"start"} type={"string"} required={false} deprecated={undefined}>
The first 4 characters of the key. If a prefix is used, it should be the prefix plus 4 characters.
<span>Example: `"unkey_32kq"`</span>
</Property>
<Property name={"ownerId"} type={"string"} required={false} deprecated={undefined}>
Your user’s Id. This will provide a link between Unkey and your customer record.
When validating a key, we will return this back to you, so you can clearly identify your user from their api key.
<span>Example: `"team_123"`</span>
</Property>
<Property name={"meta"} type={"object"} required={false} deprecated={undefined}>
This is a place for dynamic meta data, anything that feels useful for you should go here
<span>Example: `{"billingTier":"PRO","trialEnds":"2023-06-16T17:16:37.161Z"}`</span>
<ObjectCollapsible name={"meta"}>
<Property name={"[key: string]"} type={"null"} required={false} deprecated={undefined}>
</Property>
</ObjectCollapsible>
</Property>
<Property name={"roles"} type={"array of string"} required={false} deprecated={undefined}>
A list of roles that this key should have. If the role does not exist, an error is thrown
<span>Example: `["admin","finance"]`</span>
</Property>
<Property name={"permissions"} type={"array of string"} required={false} deprecated={undefined}>
A list of permissions that this key should have. If the permission does not exist, an error is thrown
<span>Example: `["domains.create_record","say_hello"]`</span>
</Property>
<Property name={"expires"} type={"integer"} required={false} deprecated={undefined}>
You can auto expire keys by providing a unix timestamp in milliseconds. Once Keys expire they will automatically be disabled and are no longer valid unless you enable them again.
<span>Example: `1623869797161`</span>
</Property>
<Property name={"remaining"} type={"integer"} required={false} deprecated={undefined}>
You can limit the number of requests a key can make. Once a key reaches 0 remaining requests, it will automatically be disabled and is no longer valid unless you update it.
<span>Example: `1000`</span>
<span>Minimum: `1`</span>
</Property>
<Property name={"refill"} type={"object"} required={false} deprecated={undefined}>
Unkey enables you to refill verifications for each key at regular intervals.
<span>Example: `{"interval":"daily","amount":100}`</span>
<ObjectCollapsible name={"refill"}>
<Property name={"interval"} type={"string"} required={true} deprecated={undefined}>
Unkey will automatically refill verifications at the set interval.
<span>Value in: `"daily" | "monthly"`</span>
</Property>
<Property name={"amount"} type={"integer"} required={true} deprecated={undefined}>
The number of verifications to refill for each occurrence is determined individually for each key.
<span>Minimum: `0`</span>
</Property>
</ObjectCollapsible>
</Property>
<Property name={"ratelimit"} type={"object"} required={false} deprecated={undefined}>
Unkey comes with per-key ratelimiting out of the box.
<span>Example: `{"type":"fast","limit":10,"refillRate":1,"refillInterval":60}`</span>
<ObjectCollapsible name={"ratelimit"}>
<Property name={"async"} type={"boolean"} required={false} deprecated={undefined}>
Async will return a response immediately, lowering latency at the cost of accuracy.
<span>Default: `false`</span>
</Property>
<Property name={"type"} type={"string"} required={false} deprecated={true}>
Fast ratelimiting doesn't add latency, while consistent ratelimiting is more accurate.
<span>Default: `"fast"`</span>
<span>Value in: `"fast" | "consistent"`</span>
</Property>
<Property name={"limit"} type={"integer"} required={true} deprecated={undefined}>
The total amount of burstable requests.
<span>Minimum: `1`</span>
</Property>
<Property name={"refillRate"} type={"integer"} required={true} deprecated={true}>
How many tokens to refill during each refillInterval.
<span>Minimum: `1`</span>
</Property>
<Property name={"refillInterval"} type={"integer"} required={true} deprecated={true}>
Determines the speed at which tokens are refilled, in milliseconds.
<span>Minimum: `1`</span>
</Property>
</ObjectCollapsible>
</Property>
<Property name={"enabled"} type={"boolean"} required={false} deprecated={undefined}>
Sets if key is enabled or disabled. Disabled keys are not valid.
<span>Example: `false`</span>
<span>Default: `true`</span>
</Property>
<Property name={"environment"} type={"string"} required={false} deprecated={undefined}>
Environments allow you to divide your keyspace.
Some applications like Stripe, Clerk, WorkOS and others have a concept of "live" and "test" keys to
give the developer a way to develop their own application without the risk of modifying real world
resources.
When you set an environment, we will return it back to you when validating the key, so you can
handle it correctly.
<span>Maximum length: `256`</span>
</Property>
</ObjectCollapsible>
</Property>
| Status code | Description |
@@ -526,7 +764,7 @@ The id of the api, you want to migrate keys to
<Property name={"keys"} type={"array of object"} required={true} deprecated={undefined}>
<ObjectCollapsible name={"keys"}>
<ObjectCollapsible name={"Object 1"}>
<Property name={"prefix"} type={"string"} required={false} deprecated={undefined}>
@@ -537,7 +775,7 @@ For example Stripe famously prefixes their customer ids with cus_ or their api k
The underscore is automatically added if you are defining a prefix, for example: "prefix": "abc" will result in a key like abc_xxxxxxxxx
<span>Maximum length: `8`</span>
<span>Maximum length: `8`</span>
</Property>
@@ -545,7 +783,7 @@ The underscore is automatically added if you are defining a prefix, for example:
The name for your Key. This is not customer facing.
<span>Example: `"my key"`</span>
<span>Example: `"my key"`</span>
</Property>
@@ -571,7 +809,7 @@ The hashed and encoded key
The algorithm for hashing and encoding, currently only sha256 and base64 are supported
<span>Value in: `"sha256_base64"`</span>
<span>Value in: `"sha256_base64"`</span>
</Property>
@@ -583,7 +821,7 @@ The algorithm for hashing and encoding, currently only sha256 and base64 are sup
The first 4 characters of the key. If a prefix is used, it should be the prefix plus 4 characters.
<span>Example: `"unkey_32kq"`</span>
<span>Example: `"unkey_32kq"`</span>
</Property>
@@ -592,7 +830,7 @@ The first 4 characters of the key. If a prefix is used, it should be the prefix
Your user’s Id. This will provide a link between Unkey and your customer record.
When validating a key, we will return this back to you, so you can clearly identify your user from their api key.
<span>Example: `"team_123"`</span>
<span>Example: `"team_123"`</span>
</Property>
@@ -600,7 +838,7 @@ When validating a key, we will return this back to you, so you can clearly ident
This is a place for dynamic meta data, anything that feels useful for you should go here
<span>Example: `{"billingTier":"PRO","trialEnds":"2023-06-16T17:16:37.161Z"}`</span>
<span>Example: `{"billingTier":"PRO","trialEnds":"2023-06-16T17:16:37.161Z"}`</span>
<ObjectCollapsible name={"meta"}>
@@ -616,7 +854,7 @@ This is a place for dynamic meta data, anything that feels useful for you should
A list of roles that this key should have. If the role does not exist, an error is thrown
<span>Example: `["admin","finance"]`</span>
<span>Example: `["admin","finance"]`</span>
</Property>
@@ -624,7 +862,7 @@ A list of roles that this key should have. If the role does not exist, an error
A list of permissions that this key should have. If the permission does not exist, an error is thrown
<span>Example: `["domains.create_record","say_hello"]`</span>
<span>Example: `["domains.create_record","say_hello"]`</span>
</Property>
@@ -632,7 +870,7 @@ A list of permissions that this key should have. If the permission does not exis
You can auto expire keys by providing a unix timestamp in milliseconds. Once Keys expire they will automatically be disabled and are no longer valid unless you enable them again.
<span>Example: `1623869797161`</span>
<span>Example: `1623869797161`</span>
</Property>
@@ -640,9 +878,9 @@ You can auto expire keys by providing a unix timestamp in milliseconds. Once Key
You can limit the number of requests a key can make. Once a key reaches 0 remaining requests, it will automatically be disabled and is no longer valid unless you update it.
<span>Example: `1000`</span>
<span>Example: `1000`</span>
<span>Minimum: `1`</span>
<span>Minimum: `1`</span>
</Property>
@@ -650,7 +888,7 @@ You can limit the number of requests a key can make. Once a key reaches 0 remain
Unkey enables you to refill verifications for each key at regular intervals.
<span>Example: `{"interval":"daily","amount":100}`</span>
<span>Example: `{"interval":"daily","amount":100}`</span>
<ObjectCollapsible name={"refill"}>
@@ -658,7 +896,7 @@ Unkey enables you to refill verifications for each key at regular intervals.
Unkey will automatically refill verifications at the set interval.
<span>Value in: `"daily" | "monthly"`</span>
<span>Value in: `"daily" | "monthly"`</span>
</Property>
@@ -666,7 +904,7 @@ Unkey will automatically refill verifications at the set interval.
The number of verifications to refill for each occurrence is determined individually for each key.
<span>Minimum: `0`</span>
<span>Minimum: `0`</span>
</Property>
@@ -678,7 +916,7 @@ The number of verifications to refill for each occurrence is determined individu
Unkey comes with per-key fixed-window ratelimiting out of the box.
<span>Example: `{"type":"fast","limit":10,"duration":60000}`</span>
<span>Example: `{"type":"fast","limit":10,"duration":60000}`</span>
<ObjectCollapsible name={"ratelimit"}>
@@ -686,7 +924,7 @@ Unkey comes with per-key fixed-window ratelimiting out of the box.
Async will return a response immediately, lowering latency at the cost of accuracy.
<span>Default: `true`</span>
<span>Default: `true`</span>
</Property>
@@ -694,9 +932,9 @@ Async will return a response immediately, lowering latency at the cost of accura
Deprecated, use `async`. Fast ratelimiting doesn't add latency, while consistent ratelimiting is more accurate.
<span>Default: `"fast"`</span>
<span>Default: `"fast"`</span>
<span>Value in: `"fast" | "consistent"`</span>
<span>Value in: `"fast" | "consistent"`</span>
</Property>
@@ -704,7 +942,7 @@ Deprecated, use `async`. Fast ratelimiting doesn't add latency, while consistent
The total amount of requests in a given interval.
<span>Minimum: `1`</span>
<span>Minimum: `1`</span>
</Property>
@@ -712,9 +950,9 @@ The total amount of requests in a given interval.
The window duration in milliseconds
<span>Example: `60000`</span>
<span>Example: `60000`</span>
<span>Minimum: `1000`</span>
<span>Minimum: `1000`</span>
</Property>
@@ -722,7 +960,7 @@ The window duration in milliseconds
How many tokens to refill during each refillInterval.
<span>Minimum: `1`</span>
<span>Minimum: `1`</span>
</Property>
@@ -730,7 +968,7 @@ How many tokens to refill during each refillInterval.
The refill timeframe, in milliseconds.
<span>Minimum: `1`</span>
<span>Minimum: `1`</span>
</Property>
@@ -742,9 +980,9 @@ The refill timeframe, in milliseconds.
Sets if key is enabled or disabled. Disabled keys are not valid.
<span>Example: `false`</span>
<span>Example: `false`</span>
<span>Default: `true`</span>
<span>Default: `true`</span>
</Property>
@@ -760,7 +998,7 @@ When you set an environment, we will return it back to you when validating the k
handle it correctly.
<span>Maximum length: `256`</span>
<span>Maximum length: `256`</span>
</Property>
packages/openapi/test/out/unkey/ratelimits.mdx
+16 -16
View File
@@ -27,9 +27,9 @@ In: `header`
Namespaces group different limits together for better analytics. You might have a namespace for your public API and one for internal tRPC routes.
<span>Example: `"email.outbound"`</span>
<span>Example: `"email.outbound"`</span>
<span>Default: `"default"`</span>
<span>Default: `"default"`</span>
</Property>
@@ -37,7 +37,7 @@ Namespaces group different limits together for better analytics. You might have
Identifier of your user, this can be their userId, an email, an ip or anything else.
<span>Example: `"user_123"`</span>
<span>Example: `"user_123"`</span>
</Property>
@@ -45,9 +45,9 @@ Identifier of your user, this can be their userId, an email, an ip or anything e
How many requests may pass in a given window.
<span>Example: `10`</span>
<span>Example: `10`</span>
<span>Minimum: `0`</span>
<span>Minimum: `0`</span>
</Property>
@@ -55,9 +55,9 @@ How many requests may pass in a given window.
The window duration in milliseconds
<span>Example: `60000`</span>
<span>Example: `60000`</span>
<span>Minimum: `1000`</span>
<span>Minimum: `1000`</span>
</Property>
@@ -68,11 +68,11 @@ If there are not enough tokens left, the request is denied.
Set it to 0 to receive the current limit without changing anything.
<span>Example: `2`</span>
<span>Example: `2`</span>
<span>Default: `1`</span>
<span>Default: `1`</span>
<span>Minimum: `0`</span>
<span>Minimum: `0`</span>
</Property>
@@ -80,7 +80,7 @@ Set it to 0 to receive the current limit without changing anything.
Async will return a response immediately, lowering latency at the cost of accuracy.
<span>Default: `false`</span>
<span>Default: `false`</span>
</Property>
@@ -102,15 +102,15 @@ Attach any metadata to this request
Resources that are about to be accessed by the user
<span>Example: `[{"type":"project","id":"p_123","name":"dub"}]`</span>
<span>Example: `[{"type":"project","id":"p_123","name":"dub"}]`</span>
<ObjectCollapsible name={"resources"}>
<ObjectCollapsible name={"Object 1"}>
<Property name={"type"} type={"string"} required={true} deprecated={undefined}>
The type of resource
<span>Example: `"organization"`</span>
<span>Example: `"organization"`</span>
</Property>
@@ -118,7 +118,7 @@ The type of resource
The unique identifier for the resource
<span>Example: `"org_123"`</span>
<span>Example: `"org_123"`</span>
</Property>
@@ -126,7 +126,7 @@ The unique identifier for the resource
A human readable name for this resource
<span>Example: `"unkey"`</span>
<span>Example: `"unkey"`</span>
</Property>
packages/ui/src/components/api.tsx
+2 -1
View File
@@ -174,11 +174,12 @@ export function TypeScriptResponse(props: {
}
export function ObjectCollapsible(props: {
name: string;
children: ReactNode;
}): React.ReactElement {
return (
<Accordions type="single">
<Accordion title="Object Type">{props.children}</Accordion>
<Accordion title={props.name}>{props.children}</Accordion>
</Accordions>
);
}