forked from AmadeusITGroup/otter
-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat(training): use markdown for step instructions
- Loading branch information
Showing
20 changed files
with
1,778 additions
and
65 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
59 changes: 59 additions & 0 deletions
59
apps/showcase/src/assets/trainings/sdk/steps/angular-integration/instructions.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,59 @@ | ||
| ### Introduction | ||
|
|
||
| When dealing with an Angular project, you will need to ensure that your `ApiClient` will be shared accross | ||
| your application.\ | ||
| The Otter framework provides the `ApiManager` service to manage your API collection. | ||
|
|
||
| #### Prerequisite | ||
|
|
||
| - Install the `@o3r/apis-manager` in the project with `npm install @o3r/apis-manager`. | ||
|
|
||
| #### Objectives | ||
|
|
||
| Leverage the `ApiManager` service to access two different clients to retrieve the list of available | ||
| pets and submit an order for the first pet returned. | ||
|
|
||
|
|
||
| Add a plugin to the `OrderApi` to log each time a call is sent. | ||
|
|
||
| # Exercise | ||
|
|
||
| Integrate the `ApiManager` in your application module and configure it to use the `RequestLogPlugin` in the `OrderApi`.\ | ||
| You can inspire yourself with the following lines: | ||
|
|
||
| ```typescript | ||
| // Default configuration for all the APIs defined in the ApiManager | ||
| const apiConfig: ApiClient = new ApiFetchClient( | ||
| { | ||
| basePath: 'https://petstore3.swagger.io/api/v3', | ||
| requestPlugins: [], | ||
| fetchPlugins: [], | ||
| logger | ||
| } | ||
| ); | ||
| const apiManager = new ApiManager(apiConfig, { | ||
| // Configuration override for a specific API | ||
| OrderApi: new ApiFetchClient({ | ||
| basePath: 'https://petstore3.swagger.io/api/v3', | ||
| requestPlugins: [new RequestLogPlugin()], | ||
| fetchPlugins: [], | ||
| logger | ||
| }) | ||
| }); | ||
|
|
||
| export const appConfig: ApplicationConfig = { | ||
| providers: [], | ||
| imports: [ApiManagerModule.forRoot(apiManager)] | ||
| }; | ||
| ``` | ||
|
|
||
| Now, check out the [app.component.ts](training://exercise/apps/tutorial-app/src/app/app.component.ts) file and inject the ApiManager to use your unique instance of the `OrderApi` and | ||
| `PetApi`.\ | ||
| In your constructor, update the `availablePets` list with the result of a call to `findPetsByStatus`. | ||
|
|
||
| Your application should be updated with the list of available pets.\ | ||
| You only need to update the submit method to order the first available item. | ||
|
|
||
| Don't forget to refresh the list of available pets once this is done. | ||
|
|
||
| Check out your terminal, the request to the `OrderApi` have been logged just as configured in the `ApiManager`. |
44 changes: 44 additions & 0 deletions
44
apps/showcase/src/assets/trainings/sdk/steps/date-sdk-generation/instructions.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,44 @@ | ||
| If your specification file includes dates, there are multiple options for the generation of your SDK. | ||
|
|
||
| For this exercise, let's consider a specific use case.\ | ||
| Imagine your SDK is used on a flight booking site, including international travel.\ | ||
| A user who is currently in France is planning a round trip from Paris to New York City.\ | ||
| These cities are in different timezones, which needs to be taken into account when the user books their flights.\ | ||
| The outbound and return flights must be relative to the timezones of the airports. | ||
|
|
||
| To do so, the dates of the flights must be of type `utils.DateTime`. | ||
|
|
||
| Also, for this flight booking site, each flight has an expiration date-time for the payment, which is relative to the user's timezone. | ||
|
|
||
| ### Exercise | ||
|
|
||
| This exercise should be done in your local environment.\ | ||
| We have provided the template and the solution on the right.\ | ||
| (Due to a Java constraint, you won't be able to generate your own SDK in the code editor provided on the right.) | ||
|
|
||
| Let's create a specification file for our flight booking site.\ | ||
| This SDK should contain a definition with the properties to book a flight: | ||
| - Origin location code | ||
| - Destination location code | ||
| - Departure date-time | ||
| - Payment expiration date | ||
|
|
||
| As mentioned above, the type of the departure date-time should be `utils.DateTime` after generation, which can be defined by setting the | ||
| type of the property to `string` and adding the `x-local-timezone` vendor.\ | ||
| Once your specification file is created, you can generate your SDK. | ||
| ```bash | ||
| yarn schematics @ama-sdk/schematics:typescript-core --spec-path ./path/to/openapi.yaml | ||
| ``` | ||
|
|
||
| As you may notice, your date object is generated as a `string` instead of `Date`.\ | ||
| This is normal since the default configuration of the SDK generator has an option `stringifyDate` that is set to `true`.\ | ||
| To ensure that the date object is generated correctly, this option needs to be set to false either through the command line or in `openapitools.json`.\ | ||
| For example: | ||
| ```bash | ||
| yarn schematics @ama-sdk/schematics:typescript-core --spec-path ./path/to/openapi.yaml --global-property stringifyDate=false | ||
| ``` | ||
|
|
||
| > [!NOTE] | ||
| > The `stringifyDate` option does not impact the generation of a `utils.Date` object. | ||
| To make sure you have generated the correct SDK locally, check out the solution in the file [src/models/base/flight/flight.ts](training://solution/src/models/base/flight/flight.ts). |
32 changes: 32 additions & 0 deletions
32
apps/showcase/src/assets/trainings/sdk/steps/introduction/instructions.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,32 @@ | ||
| ### Why an SDK? | ||
|
|
||
| If an application contains an API, there are several developer tasks that are required including a lot of redundant code.\ | ||
| These tasks include: | ||
| - Choosing the needed techniques to perform API calls | ||
| - Determining which HTTP method to use for each request | ||
| - Managing the Authorization (maybe adding request headers) and do it for each request | ||
| - Preparing the URL with any path or query parameters expected by the API endpoint | ||
|
|
||
| Let's see how we use the OpenAPI tools to handle our APIs and generate a typescript SDK codebase. | ||
|
|
||
| Check out the diagram on the right to visualize the description below. | ||
|
|
||
| The specifications of the SDK are written in an OpenAPI document, which defines or describes an API and its elements.\ | ||
| The API SDK is then generated using the OpenAPI Generator and the Otter SDK templates.\ | ||
| These template files include the API interfaces and operations, models with their corresponding revivers, and mocked APIs that can be used for testing in | ||
| spec files.\ | ||
| All these files together form the Typescript SDK. | ||
|
|
||
| This generated code is agnostic of any frontend framework.\ | ||
| Therefore, it can be used both in the backend in a NodeJS server | ||
| application or in a frontend application displayed by browsers, mobiles, smartwatches etc. | ||
|
|
||
| ### More information | ||
|
|
||
| You can find more information on the resources used through these links: | ||
|
|
||
| - [Specification](https://spec.openapis.org/oas/latest.html">OpenAPI) | ||
| - [OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator) | ||
| - [Otter SDK models hierarchy](https://github.com/AmadeusITGroup/otter/blob/main/docs/api-sdk/SDK_MODELS_HIERARCHY.md) | ||
| - [Model composition and inheritance](https://github.com/AmadeusITGroup/otter/blob/main/docs/api-sdk/COMPOSITION_INHERITANCE.md) | ||
| - [Otter SDK generator](https://github.com/AmadeusITGroup/otter/blob/main/packages/%40ama-sdk/schematics/README.md) |
41 changes: 41 additions & 0 deletions
41
apps/showcase/src/assets/trainings/sdk/steps/plugins/instructions.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,41 @@ | ||
| ### Introduction | ||
|
|
||
| Thanks to the `@ama-sdk/core` plugins, you can intercept the API requests and responses to transform their data or | ||
| perform actions such as the authentication, logging etc. | ||
|
|
||
| These plugins will be applied before sending all the API requests and after the reception of the responses. | ||
|
|
||
| #### Pre-requisite | ||
|
|
||
| - Install `@ama-sdk/core` | ||
|
|
||
| #### Objectives | ||
|
|
||
| In this tutorial, you will configure the `PetApi` to send an id that will be shared all over the session and log for all your response | ||
| with a timestamp. | ||
|
|
||
| ### Exercise | ||
|
|
||
| Create your own plugin that implements the `ReplyPlugin` interface to log the response from the server and a timestamp | ||
|
|
||
| You can inspire yourselves with the following code: | ||
| ```typescript | ||
| class LogTimestampResponsePlugin implements ReplyPlugin { | ||
| public load<K>(context: ReplyPluginContext<K>): PluginRunner<K | undefined, V> { | ||
| return { | ||
| transform: (data?: V) => { | ||
| console.log(data, new Date()); | ||
| // You could modify the response here to add new fields etc. | ||
| return ret; | ||
| } | ||
| }; | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Add the `SessionIdRequest` to the list of the API `requestPlugins` of your ApiFetchClient and | ||
| your custom logging plugin to the `replyPlugins` list. | ||
|
|
||
| Note that the Otter framework provides many other plugins to help you manage your authentication, your exceptions, revive your model etc.\ | ||
| You can have a look into the [project plugins](https://github.com/AmadeusITGroup/otter/tree/main/packages/%40ama-sdk/core/src/plugins) | ||
| for more information. |
23 changes: 23 additions & 0 deletions
23
apps/showcase/src/assets/trainings/sdk/steps/sdk-generation/instructions.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,23 @@ | ||
| ### Part 2: Generation command | ||
|
|
||
| There are several command lines available to generate an SDK depending on the use cases.\ | ||
| These cases are covered in the [documentation](https://github.com/AmadeusITGroup/otter/tree/main/packages/%40ama-sdk/schematics) of the package `@ama-sdk/schematics`. | ||
|
|
||
| #### Objective | ||
|
|
||
| Generate a new SDK repository using the previous specification file and the provided command line. | ||
|
|
||
| #### Exercise | ||
|
|
||
| To generate a new SDK repository, you can run the following command line: | ||
|
|
||
| ```bash | ||
| yarn create @ama-sdk typescript training-sdk | ||
| ``` | ||
|
|
||
| You will receive a prompt asking you to specify the project name.\ | ||
| For example, you can set the project name to `training-project`. | ||
|
|
||
| ```bash | ||
| ? Project name (NPM package scope, package.json name will be @{projectName}/{packageName})? training-project | ||
| ``` |
31 changes: 31 additions & 0 deletions
31
apps/showcase/src/assets/trainings/sdk/steps/typescript-sdk/instructions.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,31 @@ | ||
| ### Objectives | ||
|
|
||
| For this example, you will use the public PetStore project API.\ | ||
| You will perform a simple call and retrieve a list of pets from an SDK programmatically generated from their public specification.\ | ||
| As this step requires a JAVA setup, it has already been done for you.\ | ||
| You will just need to integrate the Otter SDK client and perform your call. | ||
|
|
||
| ### Exercise | ||
|
|
||
| Let's create a fetch client in your application and use it to access your API.\ | ||
| You can get inspiration from the following code: | ||
| ```typescript | ||
| const apiConfig: ApiClient = new ApiFetchClient( | ||
| { | ||
| basePath: 'https://petstore3.swagger.io/api/v3', | ||
| requestPlugins: [], | ||
| fetchPlugins: [], | ||
| logger | ||
| } | ||
| ); | ||
| const api = new PetApi(apiConfig); | ||
| ``` | ||
|
|
||
| Now, you can call the api object to perform the HTTP request you look for.\ | ||
| Have a look at the `sdk/api/pet.api.ts` folder and look for the `findPetsByStatus`. | ||
|
|
||
| For this exercise, you will look for the available items and you will only show the name of the ten first pet in the allocated | ||
| space (look for the div with the `result` id). | ||
|
|
||
| See how you can benefit from the typecheck thanks to the SDK generated interfaces. | ||
|
|
Oops, something went wrong.