Showcase SDK
Note:
This package is intended for testing purposes only. It is not suitable for production use.
Based on openapi specs 3.0.2
The SDK contains 2 different parts:
- Auto generated code (based on Swagger Spec)
- Specific code dedicated to this SDK
Structure
Auto Generated code
A main part of the SDK is automatically generated from a Swagger Spec.
The following folders contain the generated code:
- src/api: Containing the API calls files
- src/models/base: Models based of swagger definitions
The Code can be regenerated by running the following command:
yarn schematics @ama-sdk/sdk:typescript-core --spec-path [path to your swagger file]
Note that you can use npm exec
instead of yarn
for every command specified in this documentation.
Where to put my custom code?
There are 2 places where we can add custom code:
- src/helpers: should contain the helper functions to transform the data.
- src/models/custom: should contain the models specific to this SDK (mainly the helper functions return type).
How to extend a Model?
You can extend a base model in 3 steps:
- Redirect the default model to your override:
export * from "../../core/<model name>";
- Indicate to Swagger CodeGen that you have override the base model:
# in .swagger-codegen-ignore
src/models/base/<model name>/index.ts
export * from "./<model name>.ts";
export * from "./<model name>.reviver.ts";
import { <model name> as Base<model name> } from "../../base/<model name>/<model name>";
export interface <model name> extends BaseB<model name> {
// Additional fields
}
import { yourFunction } from "../../../helpers/<model name>";
import { revive<model name> as Base<model name> } from "../../base/<model name>/<model name>.reviver";
import { <model name> } from "./<model name>";
import {Reviver, utils} from "@ama-sdk/core";
export function revive<model name><T extends <model name> = <model name>>(data: any, dictionary?: any) {
// TODO: use BaseRevive<T> when ready
const revivedData: T | undefined = Base<model name>(data, dictionary) as T | undefined;
if (!revivedData) { return ; }
if (!revivedData.yourField) {
revivedData.yourField = yourFunction(revivedData);
}
return revivedData;
}
Commands
Some commands are provided to keep your SDK up-to-date.
Generate SDK from a Swagger specification
yarn spec:regen
Run Unit Tests
You can build and run UT with:
yarn test
Manage dates
The timezone issue
Managing dates with timezones has always been a bit painful in front end applications.
Let's give a concrete example to understand the problem:
An API returns the date and hour of your flight in the timezone of the airport location. In our use case, let's say the departure airport is on GTM+7 : 2023-07-10T00:37:00.000+07:00.
The timezone sent is the one from the airport, here GMT+7. If you just use the Date(), the computer browser will convert this in its own timezone.
For example, if the user is in GMT+2 you will end up displaying the following: 2023-07-09T19:37:00.000+02:00.
This is not what you want. You want the exact date time of the flight at the airport timezone, not the one of your user's computer.
However, there might be cases where you might still need the timezone information.
For example, you want to be able to display that the flight is in X hours.
You will need to compute this information with the two timezones -- the airport's and the user's.
Solution proposed to remove the timezone: utils.DateTime
The Otter framework has introduced the utils.Date
and utils.DateTime
objects to replace the Date
implementation and convert the date returned by the API as if it were in the
timezone of the user.
Dates can be generated as utils.Date
or string
depending on the value of the stringifyDate
option. This ensures that the timezone will not impact the date.
In the case of date-time
object, the default type used is string
or native Date
depending on the stringifyDate
option value.
If you want to generate a date-time using utils.DateTime
, you can do it at property level thanks to the x-local-timezone
vendor.
As this field does not exist in the specification, it will not be part of the base model but of the core model instead (the first one being completely generated from the API specifications).
Simple example:
Flight:
type: "object"
required:
- departureDateTime
properties:
departureDateTime:
type: string
x-local-timezone: true
description: If this vendor extension is present send dates without their timezone
format: date-time
Base model generated
export interface Flight {
departureDateTime: utils.DateTime;
}
You need to create a core model to store the timezone information (src/models/core/flight.ts):
import type { IgnoreEnum } from '@ama-sdk/core';
import type { Flight } from '../../base/flight/flight';
export type FlightStopCoreIfy<T extends IgnoreEnum<Flight>> = T & {
departureDateTimeConsideringTimezone?: Date;
};
And an associated reviver (src/models/core/flight.reviver.ts):
import type { Flight } from '../../base/flight/flight';
import type { reviveFlight } from '../../base/flight/flight.reviver';
import type { FlightCoreIfy } from './flight';
export function reviveFlightFactory<R extends typeof reviveFlight>(baseRevive: R) {
const reviver = <T extends Flight = Flight>(data: any, dictionaries?: any) => {
const originalData: any = {...data};
const revivedData = baseRevive<FlightCoreIfy<T>>(data, dictionaries);
if (!revivedData) {
return;
}
revivedData.departureDateTimeConsideringTimezone = originalData.departureDateTimeConsideringTimezone && new Date(originalData.departureDateTimeConsideringTimezone)
|| originalData.departureDateTime && new Date(originalData.departureDateTime);
return revivedData;
};
return reviver;
}
And export it here (src/models/core/flight/index.ts):
export * from './flight';
export * from './flight.reviver';
And here (src/models/core/index.ts):
export * from './flight/index';
You can now use departureDateTimeConsideringTimezone to access the timezone information.
See utils.Date for more information.