Tsoa: summary & description - Api Parameters

[zarubto4]

Hi, first thx for you work!

But is possible to add new Anotation ? For example we used "@Tags('Person')" its nice, but according to the Swagger documentation we can use other "labels" that we would like to use.

"summary" : "get something short",
"description" : "long description set in code in anotation"

   ..... 
   @Tags('Person')
   @Summary("something") 
   @Description("something long") 
   .....

[taicho]

Could there be a dummy @Custom decorator that could be used in place of any missing decorators as a way to allow use of new OpenAPI spec properties as they roll out.

Example:
@Custom('Summary','Fee fi fo fum')
@Custom('Description','Some endpoint');

I am debating on using TSOA on a large project and have been experimenting with it but the lack of this ability makes me concerned about it's longterm viability - I would be totally satisfied with this sort of "Custom" decorator in place to hedge against future changes and take the pressure off of @lukeautry from having to add a decorator for every existing or new property in the OpenAPI spec... Worst case I'll fork and add this but it would be nice to have it authored.

[zarubto4]

We used swagger anotation in PlayFramework in Java on really huge project. And TSOA has the potential. But it is not complete for huge projects. (I do not want to criticize, you do a good job guys!)

If you are working on a big projects, then you need these conveniences (decorators). Mainly for clear and prety code, complete documentation, OpenAPI spec properties as they roll out and also parsable parameters for "Lint". And it's also better to read it in annotations when I check my colleagues' code..

It looks like this in Java..

[slapersonne]

Description and Summary are handled through JSDoc, for example with the following code :

/**
 * Get the type for a given typeApiId
 *
 * @summary Get a type
 * 
 * @param {string} typeApiId UUID of the type to search
 */
@Get("types/{typeApiId}")
public getType(@Path("typeApiId") typeApiId: string) {
    [...]
}

tsoa will generate the following swagger file :

"/types/{typeApiId}":
{
  "get":
  {
    "operationId":"GetType",
    "description":"Get the type for a given typeApiId",
    "summary":"Get a type",
    "parameters":[
      {
        "description":"UUID of the type to search",
        "in":"path",
        "name":"typeApiId",
        "required":true,
        "type":"string"
      }
    ]
  }
}

[endor]

There's also a @Tags decorator.

@zarubto4 Is this enough for you or do you need some other annotations as well?

[karpoff]

jsonDocs doesn't work for Body properties
I've added my parameter to @param of jsdoc and as @BodyProp. And in swagger I see whole body as single parameter

[lukeautry]

I believe this would be solved by #347. We likely wouldn't support Summary and Description and standalone decorators.