@webpieces/openapi-generator weekly downloads statistics

@webpieces/openapi-generator

Render a webpieces API contract to OpenAPI 3.1.0.

wp-openapi --manifest path/to/openapi.manifest.json --out path/to/dist [--format json|yaml|both]

Which documents you get is a property of your CONTRACTS

@ApiPath('/stores')
@ApiType(SVC_TO_SVC, EXTERNAL_CUSTOMER)     // which documents this contract feeds
export abstract class StoreApi { ... }

@ApiType value	file	contents
SVC_TO_SVC	full-private-openapi.json	every method, hidden ones included, plus an internal-use-only line in info.description. Nothing renders it for humans
EXTERNAL_CUSTOMER	public-openapi.json	the customer contract, minus every { hidden: true } method and every @hidden field
MCP	mcp-openapi.json	the same contracts with the x-mcp-* extensions an MCP generator reads

A document no contract declares is not written. No @ApiType at all means SVC_TO_SVC only — fail-closed: a contract reaches customers by SAYING SO, so grep -rn EXTERNAL_CUSTOMER is your entire customer-facing surface on one screen.

--format picks the serialization of whichever documents exist, and defaults to both.

diff full-private-openapi.json public-openapi.json is the complete list of what you do not show a customer. Neither is committed — both are build output (see "In an nx workspace" below); diff the two the build wrote when you need that list.

Hiding ONE method

/**
 * Rebuilds a store's menu cache.
 *
 * Not published: an operator tool, and the customer contract has no concept of our cache.
 */
@Endpoint(POST, '/reindex', WRITE, RPC, { hidden: true })

The reason goes in the JSDoc — where the rest of the endpoint's documentation already lives. The method is absent from public-openapi.json: no path, no operation, no schema, no prose, and nothing announcing that anything was withheld.

Hiding is a documentation decision and never an access-control one. The route is still served and still demands whatever credential it declares.

Hiding ONE field

export class OrderDto {
    orderId!: string;
    /**
     * Estimated delivery time, ISO-8601.
     * @hidden not announced yet; ships with the delivery-ETA launch
     * @format date-time
     */
    deliveryEta?: string;
}

The @hidden JSDoc tag withholds one field from public-openapi.json and its bundled sibling — its property, its prose and its required entry — everywhere the schema is written: request and response bodies, nested $ref targets, inherited fields, webhook payloads, inlined single-use wrappers. A type reached ONLY through a hidden field is not in the customer document at all. The field stays in full-private-openapi.json, and in the MCP output (mcp-openapi.json and the tool catalogs), exactly like a { hidden: true } method. The tag's text is the author's reason and is published nowhere. grep -rn "@hidden" lists every withheld field.

Generation refuses:

• a hidden field that is REQUIRED — the customer document would omit a property the server insists on; make it optional (name?:);
• a type whose EVERY field is hidden — hide the method or the field holding the type instead;
• a {@link} to a hidden field from prose the customer document carries;
• a hidden field on a type the split customer document $refs into ANOTHER package's components.openapi.json — that document serves every audience and cannot withhold it; declare the type in the contract's own package.

@hidden is for a field that was NEVER published. Hiding a field a partner already reads is a removal from their side, and the generator has no baseline to notice it. It is also documentation only: the server still accepts and returns the field.

The manifest

It carries exactly what is not a property of the code:

{
    "title": "Example Orders API",
    "summary": "Read and cancel the orders placed at your stores.",
    "version": "1.0.0",
    "descriptionFile": "description.md",
    "servers": [{ "url": "https://api.example.com", "description": "Production." }],
    "apis": [
        { "entry": "src/OrdersApi.ts", "tag": "Orders" },
        { "entry": "src/EventsApi.ts", "tag": "Webhooks", "kind": "webhook" }
    ],
    "securitySchemeNames": ["PartnerApiKey", "PartnerOrganization"],
    "errors": {
        "entry": "src/ApiErrors.ts",
        "type": "ApiErrorResponse",
        "responses": [
            { "status": "400", "description": "The request failed validation." },
            { "status": "401", "description": "The api key is not valid.", "requiresAuth": true }
        ]
    },
    "responseHeaders": [
        {
            "entry": "src/ResponseHeaders.ts",
            "contextKey": "REQUEST_ID_KEY",
            "required": true,
            "description": "Correlates this response with our logs."
        }
    ]
}

Every path is relative to the manifest's own directory.

The API itself has the same three forms an operation has (#1296): title is info.title, the REQUIRED summary — one line, at most 200 characters, the Claude Connectors Directory's one-liner limit, so the same text can be pasted there — is OpenAPI 3.1's info.summary, and descriptionFile is info.description. A manifest with no summary, an empty one, a second line or more than 200 characters is refused, naming the key. A "kind": "components" manifest takes no summary: a DTO library's document is not an API anybody lists.

Source suffixes and published schema names

An optional schemaNames list controls published type names independently of source validation. It works in contract manifests and "kind": "components" manifests:

"schemaNames": [
  { "paths": ["../keep-my-names/**"], "stripSuffixes": [] },
  { "paths": ["../partner-apis/**", "../shared-dtos/**"], "stripSuffixes": ["Dto"] }
]
```…