tsoa-community / docs Goto Github PK

Understood. I just didn't realize that named exports were mandatory. Maybe it would be a good idea to mention this in the docs [...]

Originally posted by @kuasha420 in lukeautry/tsoa#897 (comment)

Would be great if we could make this more explicit as it seems to be unclear as of now.

See lukeautry/tsoa#920

I implement step by step the example in https://tsoa-community.github.io/docs/getting-started.html#initializing-our-project, and get an error with yarn run tsoa routes

Also, would be a good idea to include documentation regarding how to integrate with other middle wares that aren't officially supported.

Hi! I'm new to tsoa and started looking through the docs, but I noticed that a link on the Getting Started page is 404ing, specifically at https://github.com/tsoa-community/docs/blame/master/getting-started.md#L66.

I'd open a PR to fix but I'm not actually sure what the correct thing to link to is 😅

https://tsoa-community.github.io/docs/authentication.html

In the first section, two securityDefinitions are defined: api_key and tsoa_auth, however, in the following, api_token and jwt are used. This is a bit confusing and should probably be aligned.

In the docs, it says

For a full list of all the possible config, take a look at the API Reference

But this link is broken. Not the first time this has happened in case this is useful context (see #16)

Copied over from lukeautry/tsoa#809

This is a request for clarification in the docs:

The docs give examples for how to integrate tsoa with inversify (link). That part of the documentation also states that We usually don't want to create a new controller instance for every call, so let's create a convenience wrapper around @fluentProvide(), and provides an example of binding a controller to the IOC container in the singleton scope.

This is very reasonable — no point instantiating new controller instances if not necessary, so let's re-use the same instance for each request. However, since the Controller.setHeaders method mutates the controller state, calling setHeaders will modify the headers for every subsequent request to the same controller instance. This is pretty surprising, and took me a while to debug.

Would it be possible to clarify this behavior in the docs?

The error handling page leaves off an import in the example

if (err instanceof ValidateError)

Requires the import

import { ValidateError } from 'tsoa';

which is missing from the page and preceding examples

Next to the description field, OpenAPI supports summaries in many cases.
tsoa uses these on the method level:

  /**
   * @summary simple summary
   */
  @Get('SummaryMethod')
  public async summaryMethod(): Promise<TestModel> {
    return new ModelService().getModel();
  }

However, this is not documented yet.

The IOC docs state "We usually don't want to create a new controller instance for every call" - Why is this safe?

Given a controller like this:

@Route("users")
@provideSingleton(UsersController)
export class UsersController extends Controller {
  @Get("{userId}")
  public async getUser(
    @Path() userId: number,
    @Query() name?: string
  ): Promise<User> {
	const userService = new UsersService();
    return await userService.get(userId, name);
  }

  @SuccessResponse("201", "Created")
  @Post()
  public async createUser(
    @Body() requestBody: UserCreationParams
  ): Promise<void> {
	const userService = new UsersService();
    this.setStatus(201); // race-condition?
    await userService.create(requestBody);
    return;
  }
}

Isn't there now a race-condition with the setStatus(201) call potentially affecting another request, maybe even for another route? Or am I confused? - If I'm not, I think the quoted sentence should go away, and we should change the example to use a controller per-requests, since it's unsafe in a lot of cases and the controller reuse is likely an unnecessary optimization anyway.