feat: add tsoa for API type control and documentation by Andreybest · Pull Request #1501 · finos/git-proxy

Andreybest · 2026-04-10T12:54:06Z

Resolves #1430.

Add tsoa for endpoint type checking and generation of OpenAPI documentation. Generates swagger.json to /dist folder.
All tests for endpoints that were present, passes (with minor changes), all logic is preserved.

Caveats:

tsoa checks for field presence, but does not check if string in field is empty, thus should be checked manually (or I've missed something in configuration). For example: POST api/v1/push/{id}/reject (rejectPush), if empty or whitespaces provided, will not check for it, thus old logic for theck with .trim() is left.
tsoa has a configuration field noImplicitAdditionalProperties, that allows to change behavior of endpoints for rejecting of excess fields. Currently set to ignore due to POST api/v1/repo (createRepo), this endpoint passes body to a db.createRepo(body), and inner type expects additionalProperties that are passed to a row in a DB. Question: is this expected or not? If not, maybe we should enable more strict mode on noImplicitAdditionalProperties? :)

netlify · 2026-04-10T12:54:13Z

✅ Deploy Preview for endearing-brigadeiros-63f9d0 canceled.

Name	Link
🔨 Latest commit	`9520a31`
🔍 Latest deploy log	https://app.netlify.com/projects/endearing-brigadeiros-63f9d0/deploys/69e81cb7c615fb0008b12e37

jescalada

Thanks for the contribution, @Andreybest! 🚀

Things are looking good so far, just a few things to mention other than the code comments:

It'd be great to have screenshots of the generated OpenAPI spec to see if things are working as we hoped
I noticed a duplicate interface (AttestationAnswer) and am wondering if there aren't other interfaces that can be reused or combined into one
Test coverage seems to go down somewhat (-1.5%), we should improve coverage on any code additions such as proxyStore.ts, etc.

We might need another review since the changes are quite large @finos/git-proxy-maintainers

jescalada · 2026-04-13T14:02:04Z

    "start": "concurrently \"npm run server\" \"npm run client\"",
    "build": "npm run generate-config-types && npm run build-ui && npm run build-ts",
-    "build-ts": "tsc --project tsconfig.publish.json && node scripts/fix-shebang.js",
+    "build-ts": "npm run build-tsoa && tsc --project tsconfig.publish.json && node scripts/fix-shebang.js",


Wonder if this can be simplified or done elsewhere? I feel the build-ts script is starting to get too cluttered. Perhaps we could rename the build-tsoa script from below to something more descriptive like build-api-spec, and then call build-api-spec && build-ts when needed?

Feel free to suggest alternatives 🙂

build-tsoa builds swagger.json and generatedRoutes.ts which is required for index.ts, without it - build fails, so its is essential part of a build (unfortunately). Considering this thing, build-tsoa naming makes more sense than build-api-spec because we build spec and routes (tsoa spec-and-routes).

jescalada · 2026-04-13T14:10:09Z

It seems Git mistakenly interpreted this as a rename... Don't think much can be done here since the diff looks valid 👍🏼

jescalada · 2026-04-13T14:26:46Z

If I understand correctly, this is a rewrite of /src/service/passport/jwtAuthHandler.ts? Is this necessary, and if so, should we delete that version instead?

We should double check that all usages of jwtAuthHandler still work as intended.

Unfortunatelly - yes. TSOA expect an expressAuthentication with a different set of rules. Deleted /src/service/passport/jwtAuthHandler.ts. Yes, it is the rewrite.
Checked and fixed tests for jwtAuth

jescalada · 2026-04-13T14:32:02Z

+
+// ---------- Response types ----------
+
+interface AuthResources {


If possible, these types should be stored in a separate file and imported here (and in other controllers) if necessary

Moved to /interfaces/{controller_name}.interfaces.ts, please let me know if that is alright :)

jescalada · 2026-04-13T14:36:06Z

+  }
+
+  // TODO: provide separate auth endpoints for each auth strategy or chain compatibile auth strategies
+  // TODO: if providing separate auth methods, inform the frontend so it has relevant UI elements and appropriate client-side behavior


I'm aware these comments were here before, but I believe the /auth/config endpoint is being used in the UI right now to fetch the auth methods. I think we can safely delete the "seperate auth methods" one.

jescalada · 2026-04-14T01:21:29Z

+
+    if (currentHosts.length < previousHosts.length) {
+      console.log('Restarting the proxy to remove a host');
+      const proxy = getProxy();


Another bit to double-check for proper restart behaviour

jescalada · 2026-04-14T01:31:33Z

Maybe the request/response interfaces could be stored here?

Moved to common.interfaces.ts. To follow naming with other responses/requests

jescalada · 2026-04-14T01:40:43Z

+ * When `username` is supplied the request is pre-authenticated via middleware,
+ * simulating a session-authenticated user.
+ */
+const newApp = (username?: string, isAdmin = false): Express => {


Same as the comment on users.test.ts, I don't think setting isAuthenticated is necessary as it's exclusively used for the jwtAuthHandler which is disabled by default.

jescalada · 2026-04-14T01:44:32Z

    app = express();
    app.use(express.json());
-    app.use('/users', usersRouter);
+    // Pre-authenticate so JWT security allows through in tests.


This comment is a bit misleading - JWT auth isn't required by default. The isAuthenticated flag is used only for JWT anyways and shouldn't be necessary here AFAIK 🤔

jescalada · 2026-04-14T01:49:44Z

+  "spec": {
+    "outputDirectory": "dist",
+    "specVersion": 3,
+    "securityDefinitions": {


Might be worth mentioning that JWT API auth is optional - and might be subject to change as it's a feature only used by our org. It's a bit confusing and poorly documented so we'll be polishing things once v2 is out...

In this case, it is only used for 2 things:

For a name in the decorator to be used as Security('jwt')

As a documentation for OpenAPI

It does not do any functionally, but it is required anyway if we want to use Security decorator properly

kriswest · 2026-04-20T16:39:19Z

@jescalada and @Andreybest There is a docusaurus plugin for rendering OpenAPI docs at:

https://docusaurus-openapi.tryingpan.dev/
https://github.com/PaloAltoNetworks/docusaurus-openapi-docs

Whereas in the FDC3 website we use a very simple static page and the Redoc lib to render the same: https://github.com/finos/FDC3/blob/main/website/src/pages/schemas/next/app-directory.html

Note that you have to link to this as an external link or docusaurus will return a 404 when navigating within the site:

https://github.com/finos/FDC3/blob/ffea3be0735bdd7a72ffba5473addfe49535833e/website/docs/app-directory/spec.md?plain=1#L7-L13

Andreybest · 2026-04-22T01:00:55Z

Thank you for the review @jescalada !
Can you please review it again? Applied changes to most of your comments :)

Screenshot of swagger

2. Duplicate removed, quickly checked, should be no more repetiotions (but not sure) 3. Don't see a message from code cov bot on this matter, can you please show me where I can find a code coverage stats?

Andreybest · 2026-04-22T01:09:18Z

Checked all commits on main branch for new changes to logic for endpoints. None was changed, checked up to commit 6981427c50a5e5ccd3e91a2d4229b27135f8dcc3

feat: add tsoa for API type control and documentation

474500d

Andreybest requested a review from a team as a code owner April 10, 2026 12:54

Andreybest requested a review from jescalada April 10, 2026 12:54

jescalada requested changes Apr 14, 2026

View reviewed changes

This was referenced Apr 20, 2026

20th April 2026 - GitProxy Meeting Minutes #1506

Open

Generate API reference as MDX and add to website #1343

Closed

jescalada mentioned this pull request Apr 21, 2026

Render generated swagger.json for API documentation #1510

Open

Andreybest added 3 commits April 22, 2026 02:51

fix: fix review comments

19cb00c

Merge branch 'main' into 1430-api-checking-docs

538deb1

fix: regenerate package-lock.json

9520a31

Andreybest requested a review from jescalada April 22, 2026 21:29


		// ---------- Response types ----------

		interface AuthResources {

Conversation

Andreybest commented Apr 10, 2026

Uh oh!

netlify Bot commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for endearing-brigadeiros-63f9d0 canceled.

Uh oh!

jescalada left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kriswest commented Apr 20, 2026

Uh oh!

Andreybest commented Apr 22, 2026

Uh oh!

Andreybest commented Apr 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

netlify Bot commented Apr 10, 2026 •

edited

Loading