auto-generated api docs, typed request objects, and request validation

[zRosenthal]

1. Typed Request Body

• Request would become a generic class (or could create derived Requests classes)
• Provide methods specifically for getting body, query, and path parameters to enable type checking
  • request.getBodyParam('could force this to be keyof BodyObject')

2. Validating Request Body (maybe querystring and path params too)

• A simple solution would be to provide a validate method in the abstract controller that accepts an object and a Class/Schema to validate against.
• We can eliminate the need for calling a validate method by using decorators. We need a decorator to tell us what Class/Schema to validate against.

@Validate(SomeModel)
public getPerson(request: Request<SomeModel>) { }

• Any implementation should allow the user to bring their own validator

3. Generating api docs from requests and response objects (Add functionality for generating OpenAPI 3.0 docs #60 )

• Having typed request and response objects is all but necessary for auto generating proper API Docs. Without them the user would need to define schema in decorators. I am against this as it can become error prone. I believe the code should always be the source of truth and we should do everything possible to eliminate a user from having to define things outside of normal code.
• That being said, a solution is to add a script that can be ran at build time to parse all public methods in controllers and generate docs. In order for this to work the methods will need to use a generic Request object as described above. They would also do the same for a Response object.
• The script could leverage some additional config (path to controllers, api name, etc) along with https://github.com/metadevpro/openapi3-ts to generate the api docs

I think these three things go hand and hand. A couple things to think about:

• Do any of these things belong in the core library or are they better suited as extensions?
• anything else?

[zRosenthal]

@moraneva

[zRosenthal]

@moraneva @shametim would love an opinion on these things