This package provide some tools that are used across the projects of the Digital Citizenship initiative.
To add the tools to a project:
$ yarn add -D @pagopa/openapi-codegen-tsThis tool generates TypeScript definitions of OpenAPI specs.
In simple terms it converts an OpenAPI spec like this one into:
Note: the generated models requires the runtime dependency @pagopa/ts-commons.
Up until version 12.x, when handling string pattern definitions given in the OpenAPI specifications, the production of runtime types has a bug: when using a backslash (\) for escaping regular expression digits (e.g., \d), the generator drops it. Double backslashes (\\) can be used in the pattern description as a fix for this issue. Starting from version 12.x the codegen will notify you whenever it detects a \\ inside a pattern definition as this bug has been resolved for OpenAPI 3.x.
$ gen-api-models --help
Options:
--version Show version number [boolean]
--api-spec Path to input OpenAPI spec file [string] [required]
--strict Generate strict interfaces (default: true)
[default: true]
--out-dir Output directory to store generated definition files
[string] [required]
--ts-spec-file If defined, converts the OpenAPI specs to TypeScript
source and writes it to this file [string]
--request-types Generate request types (default: false)
[default: false]
--response-decoders Generate response decoders (default:
false, implies --request-types) [default: false]
--client Generate request client SDK [default: false]
--default-success-type Default type for success responses (
default: 'undefined') [string] [default: "undefined"]
--default-error-type Default type for error responses (
default: 'undefined') [string] [default: "undefined"]
--help Show help [boolean]Example:
$ gen-api-models --api-spec ./api/public_api_v1.yaml --out-dir ./lib/api/definitions --ts-spec-file ./lib/api/public_api_v1.ts
Writing TS Specs to lib/api/public_api_v1.ts
ProblemJson -> lib/api/definitions/ProblemJson.ts
NotificationChannel -> lib/api/definitions/NotificationChannel.ts
NotificationChannelStatusValue -> lib/api/definitions/NotificationChannelStatusValue.ts
...
doneThe http client is defined in client.ts module file. It exports the following:
Client<K> which define the set of operationsK a union of keys that represent the parameters omitted by the operations (see withDefaults below)createClient<K>(parameters): Client<K> accepting the following parameters:baseUrl the base hostname of the api, including protocol and portfetchApi an implementation of the fetch-api as defined in your platform (for example: node-fetch if you are in node)basePath (optional) if defined, is appended to baseUrl for every operations. Its default is the basePath value defined in the specificationwithDefaults (optional) an adapter function that wraps every operations. It may shadow some parameters to the wrapped operations. The use case is: you have a parameter which is common to many operations and you want it to be fixed (example: a session token). WithDefaultsT<K> that defines an adapter function to be used as withDefaultsK the set of parameters that the adapter will shadowimport { createClient, WithDefaultsT } from "my-api/client";
// Without withDefaults
const simpleClient: Client = createClient({
baseUrl: `http://localhost:8080`,
fetchApi: (nodeFetch as any) as typeof fetch
});
// myOperation is defined to accept { id: string; Bearer: string; }
const result = await simpleClient.myOperation({
id: "id123",
Bearer: "VALID_TOKEN"
});
// with withDefaults
const withBearer: WithDefaultsT<"Bearer"> =
wrappedOperation =>
params => { // wrappedOperation and params are correctly inferred
return wrappedOperation({
...params,
Bearer: "VALID_TOKEN"
});
};
// this is the same of using createClient<"Bearer">. K type is being inferred from withBearer
const clientWithGlobalToken: Client<"Bearer"> = createClient({
baseUrl: `http://localhost:8080`,
fetchApi: (nodeFetch as any) as typeof fetch,
withDefaults: withBearer
});
// myOperation doesn't require "Bearer" anymore, as it's defined in "withBearer" adapter
const result = await clientWithGlobalToken.myOperation({
id: "id123"
});Bundles a generated api models and clients into a node package ready to be published into a registry.
The script is expected to be executed in the root of an application exposing an API, thus it infers package attributes from the expected ./package.json file. Values can be still overridden by provinding the respective CLI argument. To avoid this behavior, use --no-infer-attrs or -N.
$ gen-api-sdk --help
Package options:
--no-infer-attr, -N Infer package attributes from a
package.json file present in the current
directory [boolean] [default: false]
--package-name, -n, --name Name of the generated package [string]
--package-version, -V Version of the generated package [string]
--package-description, -d, --desc Description of the package [string]
--package-author, -a, --author The author of the API exposed [string]
--package-license, -L, --license The license of the API Exposed [string]
--package-registry, -r, --registry Url of the registry the package is
published in [string]
--package-access, -x, --access Either 'public' or 'private', depending of
the accessibility of the package in the
registry
[string] [choices: "public", "private"]
Code generation options:
--api-spec, -i Path to input OpenAPI spec file [string] [required]
--strict Generate strict interfaces (default: true)
[default: true]
--out-dir, -o Output directory to store generated definition files
[string] [required]
--default-success-type Default type for success responses (experimental,
default: 'undefined') [string] [default: "undefined"]
--default-error-type Default type for error responses (experimental,
default: 'undefined') [string] [default: "undefined"]
--camel-cased Generate camelCased properties name (default: false)
[default: false]
Options:
--version Show version number [boolean]
--help Show help [boolean]Takes a given api spec file and resolves its esternal references by creating a new file with only internal refereces
$ bundle-api-spec --help
Code generation options:
--api-spec, -i Path to input OpenAPI spec file [string] [required]
--out-path, -o Output path of the spec file [string] [required]
--api-version, -V Version of the api. If provided, override the version in
the original spec file [string]
Options:
--version Show version number [boolean]
--help Show help [boolean]node version >= 10.8.0Run test over utils' implementation
yarn testRun test over generated files
yarn e2eWhen using gen-api-models against a specification file which references an external definition file, some of such remote definitions do not result in a dedicated model file. This is somehow intended and the rationale is explained here. Quick takeaway is that to have a definition to result in a model file, it must be explicitly referenced by the specification file.
In short: if you need to keep the references between the generated classes, the specification file must contain all the schema definitions. See example below.
if the Pets schema uses the Pet, import both into the main document
components:
schemas:
Pets:
$ref: "animal.yaml#/Pets"
Pet:
$ref: "animal.yaml#/Pet"animal.yaml
Pets:
type: array
items:
$ref: '#/definitions/Pet'
Pet:
type: "object"
required:
- name
properties:
name:
type: stringGenerated code is slightly different from v4 as it implements some bug fixes that result in breaking changes. Here's a list of what to be aware of:
name field in the spec. This applies to both local and global parameters. In the previous version, this used to be true only for local ones, while global parameters were named after the parameter's definition name. in: header, the definition name is considered, as the name attribute refers to the actual header name to be used as for OpenApi specification.gen-api-models command, --request-types flag must be used explicitly in order to have requestTypes file generated.name attribute as the parameter name. It used to be the lower-cased reference's name instead.mkdir anymore.WithinRangeInteger or WithinRangeNumber. See [#205].
type: string and format: date used to result in a String definition, while now produce Date. #184WithinRangeInteger which maximum is the next integer to solve off-by-one comparison error. #182