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	`c4a752c`
🔍 Latest deploy log	https://app.netlify.com/projects/endearing-brigadeiros-63f9d0/deploys/6a04c5e1664d770008911f27

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-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

again probably missing a call to RegisterRoutes(app);

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

Co-authored-by: Fabio Vincenzi <93596376+fabiovincenzi@users.noreply.github.com> Signed-off-by: Andrew <andrey255@live.com>

Andreybest · 2026-05-13T18:03:20Z

Thanks for change @fabiovincenzi ! Added your suggested change.

Andreybest · 2026-05-13T18:42:42Z

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

codecov · 2026-05-13T18:46:27Z

Codecov Report

❌ Patch coverage is 85.87413% with 101 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.91%. Comparing base (ad58c5a) to head (c4a752c).

Files with missing lines	Patch %	Lines
src/service/controllers/AuthController.ts	76.43%	42 Missing and 3 partials ⚠️
src/service/controllers/PushController.ts	90.85%	15 Missing and 1 partial ⚠️
src/service/authentication.ts	77.35%	10 Missing and 2 partials ⚠️
src/service/index.ts	60.86%	9 Missing ⚠️
src/service/controllers/RepoController.ts	95.78%	7 Missing and 1 partial ⚠️
src/service/controllers/HomeController.ts	53.84%	6 Missing ⚠️
src/service/proxyStore.ts	70.00%	3 Missing ⚠️
src/app.ts	0.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1501      +/-   ##
==========================================
- Coverage   90.21%   89.91%   -0.30%     
==========================================
  Files          69       70       +1     
  Lines        5511     5486      -25     
  Branches      944      922      -22     
==========================================
- Hits         4972     4933      -39     
- Misses        521      532      +11     
- Partials       18       21       +3

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

re-vlad

just small non critical change requested

re-vlad · 2026-05-14T12:46:19Z

@@ -0,0 +1,26 @@
+{
+  "entryFile": "src/app.ts",
+  "noImplicitAdditionalProperties": "ignore",


This allows arbitrary additional properties in request bodies. The current implementation in createRepo() passes the entire body to db.createRepo(body), but this should be validated against a strict schema. The db schema should be the source of truth, not the API layer accepting arbitrary data. So, change "noImplicitAdditionalProperties": "ignore" to "noImplicitAdditionalProperties": "throw"

kriswest · 2026-05-15T12:55:07Z

 import { serverConfig } from '../config/env';
 import { Proxy } from '../proxy';
-import routes from './routes';
+import { RegisterRoutes } from './generatedRoutes';


is this file checked in @Andreybest ?

This one is generated during build

I do not commit it, you suggest it to be included in repo?

A perennial question! I've tended to go with committing it as reviewing the generated code can often help you spot issues in what its generated from, and it helps someone trying to navigate through the code to understand something. Tooling such as SAST scanners an code coverage calculators may need it to be there to work as they should.

If committing generated code, then its worth either adding a commit hook (best to check for modifications in this) or PR check box to confirm its been done ;-)

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

Closed

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

fabiovincenzi mentioned this pull request May 8, 2026

feat: generate API reference docs from OpenAPI spec #1526

Open

fabiovincenzi reviewed May 11, 2026

View reviewed changes

Comment thread package.json Outdated

Update package.json

c9704e4

Co-authored-by: Fabio Vincenzi <93596376+fabiovincenzi@users.noreply.github.com> Signed-off-by: Andrew <andrey255@live.com>

Andreybest added 2 commits May 13, 2026 20:12

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

49744f9

fix(service): fix failing git-proxy-cli test on /create-user

c4a752c

re-vlad reviewed May 14, 2026

View reviewed changes

kriswest reviewed May 15, 2026

View reviewed changes

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

Uh oh!

Andreybest commented May 13, 2026

Uh oh!

Andreybest commented May 13, 2026

Uh oh!

codecov Bot commented May 13, 2026

Codecov Report

Uh oh!

re-vlad 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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

netlify Bot commented Apr 10, 2026 •

edited

Loading