✨ feat(actions): meta.openapi für Aktionen typisieren und validieren (#40)
continuous-integration/drone/push Build is passing
continuous-integration/drone/push Build is passing
Aktionen erscheinen in der generierten OpenAPI-Spec als /_actions/<name>. Dafür trägt die Action-Meta jetzt denselben openapi-Block wie eine Sammlung: - action.schema.json: meta.openapi referenziert openapi.schema.json (bisher lehnte additionalProperties: false den Block ab). - openapi.schema.json: Beschreibung deckt Sammlung und Aktion ab, get/getOne/ post/put/delete sind entsprechend erläutert. - index.d.ts: ActionMeta.openapi plus OpenapiMeta/OpenapiOperationMeta/ OpenapiParameter. - demo-api/actions/demo-action.yml und types-test/action-openapi.ts zeigen und prüfen die Form.
This commit is contained in:
1 parent
4e13d4ab9a
commit
11069d83d4
5 files changed
+110
-8
No files matched your search
@@ -3,6 +3,19 @@ name: demo-action
|
||||
|
||||
meta:
|
||||
label: { de: Demo Aktion, en: Demo Action }
|
||||
# The action shows up in GET /_openapi/:project as /_actions/demo-action,
|
||||
# with the same override block a collection uses.
|
||||
openapi:
|
||||
get:
|
||||
summary: { de: Demo-Aktion lesen, en: Read the demo action }
|
||||
parameters:
|
||||
- name: verbose
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: boolean
|
||||
post:
|
||||
summary: { de: Demo-Aktion ausführen, en: Run the demo action }
|
||||
methods:
|
||||
get:
|
||||
query:
|
||||
|
||||
Vendored
+38
@@ -515,10 +515,48 @@ declare global {
|
||||
description?: LocalizedText
|
||||
group?: string
|
||||
hide?: boolean
|
||||
/** OpenAPI overrides, same shape a collection uses in `meta.openapi` (#40). */
|
||||
openapi?: OpenapiMeta
|
||||
methods?: Record<string, ActionMethodMeta>
|
||||
[key: string]: any
|
||||
}
|
||||
|
||||
/** `meta.openapi` of a collection or an action (GET /_openapi/:project). */
|
||||
export interface OpenapiMeta {
|
||||
/** Hide the whole collection or action from the generated spec. */
|
||||
disabled?: boolean
|
||||
/** GET: collection list, or the action itself (/_actions/{name}). */
|
||||
get?: OpenapiOperationMeta
|
||||
/** Single-entry GET of a collection (/{collection}/{id}); unused by actions. */
|
||||
getOne?: OpenapiOperationMeta
|
||||
/** POST: collection create, or the action itself (/_actions/{name}). */
|
||||
post?: OpenapiOperationMeta
|
||||
put?: OpenapiOperationMeta
|
||||
delete?: OpenapiOperationMeta
|
||||
[key: string]: any
|
||||
}
|
||||
|
||||
export interface OpenapiOperationMeta {
|
||||
/** Drop this operation from the spec. */
|
||||
disabled?: boolean
|
||||
tags?: string[]
|
||||
summary?: LocalizedText
|
||||
description?: LocalizedText
|
||||
parameters?: OpenapiParameter[]
|
||||
responses?: { [status: string]: any }
|
||||
security?: Array<{ [tokenName: string]: string[] }>
|
||||
[key: string]: any
|
||||
}
|
||||
|
||||
export interface OpenapiParameter {
|
||||
name: string
|
||||
in: "query" | "header" | "path" | "cookie"
|
||||
description?: LocalizedText
|
||||
required?: boolean
|
||||
schema?: { type?: string; [key: string]: any }
|
||||
[key: string]: any
|
||||
}
|
||||
|
||||
export interface ActionMethodMeta {
|
||||
query?: {
|
||||
title?: LocalizedText
|
||||
|
||||
@@ -428,6 +428,10 @@
|
||||
"hide": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"openapi": {
|
||||
"$ref": "openapi.schema.json",
|
||||
"description": "OpenAPI overrides for this action, same shape a collection uses in meta.openapi. The action appears as path /_actions/{name} with its get/post operations."
|
||||
},
|
||||
"methods": {
|
||||
"type": "object",
|
||||
"patternProperties": {
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"$id": "openapi.schema.json",
|
||||
"title": "Tibi OpenAPI collection config",
|
||||
"description": "OpenAPI metadata for a collection, used to generate the project's OpenAPI 3.0 spec via /_openapi/:project",
|
||||
"title": "Tibi OpenAPI entity config",
|
||||
"description": "OpenAPI metadata for a collection or an action, used to generate the project's OpenAPI 3.0 spec via /_openapi/:project. Actions appear as /_actions/{name} and use get/post.",
|
||||
"type": "object",
|
||||
"additionalProperties": true,
|
||||
"definitions": {
|
||||
@@ -161,27 +161,27 @@
|
||||
"properties": {
|
||||
"disabled": {
|
||||
"type": "boolean",
|
||||
"description": "Exclude this entire collection from the generated OpenAPI spec"
|
||||
"description": "Exclude this entire collection or action from the generated OpenAPI spec"
|
||||
},
|
||||
"get": {
|
||||
"$ref": "#/definitions/operationObject",
|
||||
"description": "OpenAPI operation overrides for the list endpoint (GET /{collection})"
|
||||
"description": "OpenAPI operation overrides for the GET endpoint: list for a collection (GET /{collection}), the action itself for an action (GET /_actions/{name})"
|
||||
},
|
||||
"getOne": {
|
||||
"$ref": "#/definitions/operationObject",
|
||||
"description": "OpenAPI operation overrides for the single-entry endpoint (GET /{collection}/{id})"
|
||||
"description": "OpenAPI operation overrides for the single-entry endpoint of a collection (GET /{collection}/{id}); unused by actions"
|
||||
},
|
||||
"post": {
|
||||
"$ref": "#/definitions/operationObject",
|
||||
"description": "OpenAPI operation overrides for the create endpoint (POST /{collection})"
|
||||
"description": "OpenAPI operation overrides for the POST endpoint: create for a collection (POST /{collection}), the action itself for an action (POST /_actions/{name})"
|
||||
},
|
||||
"put": {
|
||||
"$ref": "#/definitions/operationObject",
|
||||
"description": "OpenAPI operation overrides for the update endpoint (PUT /{collection}/{id})"
|
||||
"description": "OpenAPI operation overrides for the update endpoint of a collection (PUT /{collection}/{id}); unused by actions"
|
||||
},
|
||||
"delete": {
|
||||
"$ref": "#/definitions/operationObject",
|
||||
"description": "OpenAPI operation overrides for the delete endpoint (DELETE /{collection}/{id})"
|
||||
"description": "OpenAPI operation overrides for the delete endpoint of a collection (DELETE /{collection}/{id}); unused by actions"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,47 @@
|
||||
// Compile-time contract test for the action OpenAPI overrides (#40): an action
|
||||
// meta carries the same meta.openapi block a collection uses.
|
||||
|
||||
const meta: ActionMeta = {
|
||||
label: { de: "Kontaktformular", en: "Contact Form" },
|
||||
openapi: {
|
||||
disabled: false,
|
||||
get: {
|
||||
summary: { de: "Formular abrufen", en: "Get the form" },
|
||||
parameters: [
|
||||
{
|
||||
name: "lang",
|
||||
in: "query",
|
||||
required: false,
|
||||
schema: { type: "string" },
|
||||
},
|
||||
],
|
||||
responses: { "200": { description: "OK" } },
|
||||
security: [{ "X-Api-Token": [] }],
|
||||
},
|
||||
post: {
|
||||
summary: { de: "Formular senden", en: "Submit the form" },
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
const info: ActionInfo = {
|
||||
name: "contact-form",
|
||||
meta,
|
||||
permissions: {
|
||||
public: { methods: { post: { allow: true } } },
|
||||
},
|
||||
}
|
||||
|
||||
type _MetaIsOpenapi = Expect<Equal<NonNullable<ActionInfo["meta"]>["openapi"], OpenapiMeta | undefined>>
|
||||
type _SummaryIsLocalized = Expect<Equal<NonNullable<OpenapiMeta["get"]>["summary"], LocalizedText | undefined>>
|
||||
|
||||
const disabled: boolean | undefined = meta.openapi?.post?.disabled
|
||||
type _DisabledIsBoolean = Expect<Equal<typeof disabled, boolean | undefined>>
|
||||
|
||||
// @ts-expect-error `in` is limited to the OpenAPI parameter locations
|
||||
const badParameter: OpenapiParameter = { name: "lang", in: "body" }
|
||||
|
||||
declare const expectTrue: Expect<true>
|
||||
void expectTrue
|
||||
void info
|
||||
void badParameter
|
||||
Reference in new issue
Block a user