OpenAPI Support โ
ng-openapi generates from Swagger 2.0 and from OpenAPI 3.0, 3.1 and 3.2 documents, in JSON or YAML. This page says what is generated for each version, which OpenAPI 3.2 features are supported, and which Angular version a feature needs.
Specification Versions โ
| Version | Status | Notes |
|---|---|---|
| OpenAPI 3.2 | โ Supported | See OpenAPI 3.2 Features for the features added in this version |
| OpenAPI 3.1 | โ Supported | |
| OpenAPI 3.0 | โ Supported | |
| Swagger 2.0 | โ ๏ธ Supported with limits | in: body and in: formData parameters are not generated, and each is warned about. Responses are typed any, without a warning |
The limits on this page are reported as warnings during generation, except where the page says otherwise. A warning names the operation and says what the generated code does instead. Two things are neither followed nor reported: a path item that is a $ref (to components.pathItems or to another file), whose operations are left out, and a JSON request body or response whose media type is a $ref (to components.mediaTypes), which is typed any.
OpenAPI 3.2 Features โ
| Feature | Status | What is generated |
|---|---|---|
query operations (the HTTP QUERY method) | โ Supported | A service method, and a resource with the HTTP Resource plugin. Requires Angular 22.3+ |
additionalOperations (COPY, PURGE, custom โฆ) | โ Supported | A service method that sends the declared method. No resource: nothing says such a method is safe to repeat |
in: querystring parameters | โ Not supported | The parameter is left out, with a warning |
itemSchema (JSON Lines, Server-Sent Events, โฆ) | โ Not supported | The item schema is not read, without a warning |
The QUERY Method โ
QUERY is a safe, idempotent read like GET whose input travels in the request body, so it is not limited by URL length and can still be retried and cached. OpenAPI 3.2 declares it with the query field of a path item:
paths:
/products/search:
query:
operationId: searchProducts
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ProductSearch"
responses:
"200":
description: The matching products
content:
application/json:
schema:
$ref: "#/components/schemas/ProductPage"ng-openapi generates it with Angular's HttpClient, which supports the QUERY method from Angular 22.3:
// services/products.service.ts
searchProducts(productSearch: ProductSearch, /* observe, options */): Observable<ProductPage> {
// โฆ
return this.httpClient.request('query', url, { body: productSearch, /* โฆ */ });
}This is the same request HttpClient.query() sends; request() is used because it is the one call whose typings accept every observe and responseType the generated method offers. With the HTTP Resource plugin, the operation also becomes a resource whose body argument can be a signal.
QUERY requires Angular 22.3+
On older Angular versions the generated code still compiles and sends the request, but HttpClient treats it as a mutation: it attaches the XSRF token to the request, and server-side rendering does not reuse the response during hydration. Generation warns when it detects an older @angular/core in the workspace.
Additional Operations โ
A path item has a fixed field for each common method. Every other method is declared under additionalOperations, keyed by the method name:
paths:
/products/{productId}:
additionalOperations:
COPY:
operationId: copyProduct
requestBody: # โฆ
responses: # โฆcopyProduct(productId: string, productCopy: ProductCopy, /* observe, options */): Observable<Product> {
// โฆ
return this.httpClient.request('copy', url, { body: productCopy, /* โฆ */ });
}A few entries cannot be generated, and each is skipped with a warning:
TRACE,CONNECTandTRACK, including thetracefield of a path item: browsers refuse to send them.JSONP: Angular'sHttpClienttreats that name specially. Its XHR backend refuses it andwithJsonpSupport()turns it into a script-tag request, so whether it would be sent depends on how the app sets upHttpClient.- A method that has its own field (
POSTunderadditionalOperationsinstead ofpost), which OpenAPI does not allow. - A key that is not a valid HTTP method name.
Method names are sent upper-cased, because Angular's HttpClient upper-cases them. A key written as Copy is sent as COPY, and generation says so. Two keys that differ only by case are one method: the one written in upper case is generated, and the other is skipped with a warning. When neither is in upper case, the first is generated, with the same notice that it is sent upper-cased.
Angular Versions โ
| What you use | Angular |
|---|---|
| Generated services, models and providers | 15+ |
| HTTP Resource plugin | 19.2+ |
serviceDecorator: 'service' | 22+ |
QUERY operations | 22.3+ |
The first two are peer dependencies. The last two depend on what your configuration and your specification use, so they are checked during generation: when an older @angular/core is found in the workspace, a warning is printed and generation continues, since the workspace that runs the CLI is not always the one that compiles the output.
Request Bodies โ
A request body becomes method arguments when it is declared as application/json, multipart/form-data or application/x-www-form-urlencoded, on every method that can carry one. See Generated Output for the details and for what happens to a body under another content type.