diff --git a/demo-api/actions/demo-action.yml b/demo-api/actions/demo-action.yml index 65945ec..1cb8e8f 100644 --- a/demo-api/actions/demo-action.yml +++ b/demo-api/actions/demo-action.yml @@ -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: diff --git a/index.d.ts b/index.d.ts index 67d3320..8dd3e35 100644 --- a/index.d.ts +++ b/index.d.ts @@ -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 [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 diff --git a/schemas/config/action.schema.json b/schemas/config/action.schema.json index 834ee0c..1617fd4 100644 --- a/schemas/config/action.schema.json +++ b/schemas/config/action.schema.json @@ -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": { diff --git a/schemas/config/openapi.schema.json b/schemas/config/openapi.schema.json index 5111599..059b15f 100644 --- a/schemas/config/openapi.schema.json +++ b/schemas/config/openapi.schema.json @@ -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" } } } diff --git a/types-test/action-openapi.ts b/types-test/action-openapi.ts new file mode 100644 index 0000000..336a2ad --- /dev/null +++ b/types-test/action-openapi.ts @@ -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["openapi"], OpenapiMeta | undefined>> +type _SummaryIsLocalized = Expect["summary"], LocalizedText | undefined>> + +const disabled: boolean | undefined = meta.openapi?.post?.disabled +type _DisabledIsBoolean = Expect> + +// @ts-expect-error `in` is limited to the OpenAPI parameter locations +const badParameter: OpenapiParameter = { name: "lang", in: "body" } + +declare const expectTrue: Expect +void expectTrue +void info +void badParameter