Auto-generate TypeScript client with types from backend's documented Swagger API #1699

bnjmnt4n · 2021-04-15T09:21:00Z

Description

Using https://github.com/acacode/swagger-typescript-api, a TypeScript-based client with types is generated from the cadet backend's swagger.json.

TODO:

Add documentation
- Basic instructions
  - Copy swagger.json to src/commons/api/
  - Run yarn run update-cadet-api
Avoid typecasting
Ensure generated types are accurate
Switch from fetch to the new API globally

Type of change

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
This change requires a documentation update
Code quality improvements

How to test

Run the test suite.

Checklist

I have tested this code
I have updated the documentation

…tend into jeff/backend-v2-integration

…det-frontend into jeff/backend-v2-april

Ref. source-academy/backend#729. Prettier

… Cadet

cloudflare-workers-and-pages · 2021-04-15T09:23:46Z

Deploying with Cloudflare Pages

Latest commit:	`94db8bd`
Status:	✅ Deploy successful!
Preview URL:	https://db7968c8.cadet-frontend.pages.dev

View logs

bnjmnt4n

I wanted to get a cursory review of this PR, to see if we're going on the right track. This PR allows a TypeScript client with types defined as per the backend's Swagger API to be generated automatically using https://github.com/acacode/swagger-typescript-api. The API is properly typed to accept the correct input arguments (whether query, path, JSON or FormData), and should reflect the accurate types of the response as defined by the backend. (Note that there are still differences between the types which should be fixed before this can be merged.) The API client also parses the response into resp.data and resp.error respectively if an error occurs.

bnjmnt4n · 2021-04-15T15:53:17Z

src/commons/api/index.ts

+export const customFetch = async (
+  url: string,
+  opts: FullRequestParams
+): Promise<Response | null> => {


This customFetch function was based on the original request from RequestsSaga.

bnjmnt4n · 2021-04-15T15:56:37Z

src/commons/api/index.ts

+    if (!resp.ok) {
+      throw new Error('API call failed or got non-OK response');
+    }
+
+    return resp;
+  } catch (e) {
+    // Logout on all errors.
+    store.dispatch(actions.logOut());
+    showWarningMessage(opts.errorMessage ? opts.errorMessage : 'Please login again.');
+
+    return resp;
+  }


I've made some minor modifications to the error handling logic from the original request. The original code allowed null to be returned when errors occur. This means we have to do a lot of manual checking for null. Was there a reason for this?

bnjmnt4n · 2021-04-15T15:57:09Z

src/commons/api/index.ts

+import { actions } from '../utils/ActionsHelper';
+import Constants from '../utils/Constants';
+import { showWarningMessage } from '../utils/NotificationsHelper';
+import { Api, FullRequestParams } from './api';


The api modules is automatically generated from the swagger.json file.

bnjmnt4n · 2021-04-15T15:58:32Z

src/commons/api/index.ts

+  interface FullRequestParams {
+    accessToken?: string;
+    refreshToken?: string;
+    errorMessage?: string;
+    shouldAutoLogout?: boolean;
+    shouldRefresh?: boolean;
+  }


Here, I'm adding some custom options which can be passed into the generated API methods. Overriding the interface here was the simplest way to do it, without having to mess with the internals of the generated API.

bnjmnt4n · 2021-04-15T16:01:06Z

src/commons/api/swagger.json

@@ -0,0 +1,3361 @@
+{


This file is copied from cadet. Do you think there should be a yarn command to copy the file over for convenience?

bnjmnt4n · 2021-04-15T16:06:17Z

src/commons/sagas/RequestsSaga.ts

@@ -125,25 +127,22 @@ export const getUser = async (tokens: Tokens): Promise<User | null> => {
 * Will be updated after a separate db for student progress is ready
 */
 export const getAchievements = async (tokens: Tokens): Promise<AchievementItem[] | null> => {


I'm not sure about the semantics of redux-saga, but I'm sure there's a reason for each request function accepting tokens separately instead of just reading from the store. That being said, do you think a reasonable default for customFetch is to read from the store if no tokens are passed?

bnjmnt4n · 2021-04-15T16:07:25Z

src/commons/sagas/RequestsSaga.ts

-
+  // TODO
+  const resp = await Cadet.adminAchievements.bulkUpdate(
+    (achievements as unknown) as Achievement[],


There's still quite a bit of typecasting around the file, as there are still slight differences between the auto-generated types and the handwritten types. I'll look into all of these cases later.

angelsl · 2021-04-15T21:36:24Z

Yes, yes, so much yes. This is probably the best thing that's happened in the frontend code-quality wise ever since it was written. Looking forward to seeing this merged :)

martin-henz · 2021-06-10T10:25:34Z

Hmm, anyone looking after this PR? @bnjmnt4n ? There is enthusiastic support from @angelsl . But still in draft and currently with merge conflict...

bnjmnt4n · 2021-06-10T12:33:05Z

Sorry for the delays. I was planning to come back to it, and will take a look at it hopefully this weekend.

martin-henz · 2021-12-16T09:00:30Z

Reviewing our open PRs and this one comes up again. @bnjmnt4n do you have time these days? There is/was enthusiastic support from @angelsl . But still in draft and currently with merge conflict...

angelsl · 2021-12-16T09:16:24Z

This will need quite a bit of time to properly convert all the places in the frontend that make requests to the backend. And we need to make sure the backend Swagger definitions are accurate as well (unfortunately Elixir is dynamically typed so it's not possible to generate Swagger definitions from type information...)

It'll be tedious but worth it.

qreoct and others added 20 commits March 24, 2021 17:10

accommodate backend v2 api

1ca86c4

Merge branch 'master' of https://github.com/source-academy/cadet-fron…

004962e

…tend into jeff/backend-v2-integration

Changes to accommadate v2 backend

7f2662a

Merge branch 'master' into sa2122-backend

b231853

Merge branch 'sa2122-backend' of https://github.com/source-academy/ca…

5ecd940

…det-frontend into jeff/backend-v2-april

Avoid errors when unable to fetch room code

8758ee9

Update for new assessments endpoints

459fd7b

Ref. source-academy/backend#729. Prettier

RequestsSaga: update comments for consistency

45a47f0

Merge branch 'master' into sa2122-backend

8bc4048

Update to use /assessments/{assessmentId}/unlock API

89b0b1c

Install swagger-typescript-api

b6f8b43

Add script to generate TypeScript-compatible API client and types for…

dff3e76

… Cadet

Add custom template

17e8d94

postAcknowledgeNotifications: shift tokens to last parameter

ad7e405

Remove template

06d4ec9

Add api/index

da89b86

Add swagger.json and api.ts

f7ff1dd

Update to use generated Cadet API

3b0f530

Modify error handling

40952db

Update GameSaveRequests.ts to use Cadet API

94db8bd

bnjmnt4n force-pushed the bnjmnt4n/sa2122-backend branch from 130cc46 to 94db8bd Compare April 15, 2021 09:23

bnjmnt4n commented Apr 15, 2021

View reviewed changes

bnjmnt4n requested a review from angelsl April 15, 2021 16:13

Base automatically changed from sa2122-backend to master May 2, 2021 19:06

martin-henz added the postponed label Jun 14, 2021

martin-henz added tedious-but-worth-it help wanted Extra attention is needed and removed postponed labels Dec 16, 2021

martin-henz changed the title ~~Auto-generate TypeScript client with types from Cadet's documented Swagger API~~ Auto-generate TypeScript client with types from backend's documented Swagger API Jan 30, 2022

martin-henz closed this Feb 17, 2023

martin-henz mentioned this pull request Feb 17, 2023

Auto-generate TypeScript client with types from backend's documented Swagger API #2347

Open

martin-henz deleted the bnjmnt4n/sa2122-backend branch March 11, 2023 07:06

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Auto-generate TypeScript client with types from backend's documented Swagger API #1699

Auto-generate TypeScript client with types from backend's documented Swagger API #1699

Uh oh!

bnjmnt4n commented Apr 15, 2021 •

edited

Loading

Uh oh!

cloudflare-workers-and-pages bot commented Apr 15, 2021 •

edited

Loading

Uh oh!

bnjmnt4n left a comment

Uh oh!

bnjmnt4n Apr 15, 2021

Uh oh!

bnjmnt4n Apr 15, 2021

Uh oh!

bnjmnt4n Apr 15, 2021

Uh oh!

bnjmnt4n Apr 15, 2021

Uh oh!

bnjmnt4n Apr 15, 2021

Uh oh!

bnjmnt4n Apr 15, 2021

Uh oh!

bnjmnt4n Apr 15, 2021

Uh oh!

angelsl commented Apr 15, 2021

Uh oh!

martin-henz commented Jun 10, 2021

Uh oh!

bnjmnt4n commented Jun 10, 2021

Uh oh!

martin-henz commented Dec 16, 2021

Uh oh!

angelsl commented Dec 16, 2021

Uh oh!

Uh oh!

Auto-generate TypeScript client with types from backend's documented Swagger API #1699

Auto-generate TypeScript client with types from backend's documented Swagger API #1699

Uh oh!

Conversation

bnjmnt4n commented Apr 15, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change

How to test

Checklist

Uh oh!

cloudflare-workers-and-pages bot commented Apr 15, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying with Cloudflare Pages

Uh oh!

bnjmnt4n left a comment

Choose a reason for hiding this comment

Uh oh!

bnjmnt4n Apr 15, 2021

Choose a reason for hiding this comment

Uh oh!

bnjmnt4n Apr 15, 2021

Choose a reason for hiding this comment

Uh oh!

bnjmnt4n Apr 15, 2021

Choose a reason for hiding this comment

Uh oh!

bnjmnt4n Apr 15, 2021

Choose a reason for hiding this comment

Uh oh!

bnjmnt4n Apr 15, 2021

Choose a reason for hiding this comment

Uh oh!

bnjmnt4n Apr 15, 2021

Choose a reason for hiding this comment

Uh oh!

bnjmnt4n Apr 15, 2021

Choose a reason for hiding this comment

Uh oh!

angelsl commented Apr 15, 2021

Uh oh!

martin-henz commented Jun 10, 2021

Uh oh!

bnjmnt4n commented Jun 10, 2021

Uh oh!

martin-henz commented Dec 16, 2021

Uh oh!

angelsl commented Dec 16, 2021

Uh oh!

Uh oh!

bnjmnt4n commented Apr 15, 2021 •

edited

Loading

cloudflare-workers-and-pages bot commented Apr 15, 2021 •

edited

Loading