Routing-controllers: Feature: API documentation generator

[so3da]

Hello Guys,
It will be nice if we have a tool that uses the available action methods routings and its statically type response and request models to generate sample JSON and so on.
example:

URL: BaseURL/Users/Create
Type: POST
Sample Request

{
    "email" : "sample string",
    "username" : "sample string",
    "isMale" : true
}

Sample Response

{
    "message" : "sample string",
    "code": 1
}

[pleerock]

I didn't completely get a feature request. What kinda of documentation you want? simply json? if yes then why not generate swagger? also I didn't get what is "sample string" in your json objects

[NoNameProvided]

I think the request here is to have _automatic_ documentation generator. So if routing controller would generate documentation for the endpoints.

I think it's out of scope for routing-controllers.

[orlowdev]

Prove me wrong, but I think it's about the HATEOAS self-documented routes. I think that would be useful for generic routes (something like what Spring does with HAL browser) but when you create your own routes, you should certainly use APIDoc.

[marshall007]

@NoNameProvided while the tooling itself is certainly out of scope for routing-controllers, I think there's a lot we could do on the routing-controllers side to make projects more (easily) statically-analyzable by third-party tooling (like #122).

Obviously, we would still need to support the param and route decorators on controller class methods, but choosing to fully encapsulate your request definitions as standalone classes would enable powerful tools that use the reflection metadata for stuff like doc generators, client-side code generation, and even clients that automatically build requests as mentioned in https://github.com/pleerock/routing-controllers/issues/122#issuecomment-297855137.

[NoNameProvided]

Prove me wrong, but I think it's about the HATEOAS self-documented routes.

Dont get me wrong I like the idea. My point is as @marshall007 says as well:

while the tooling itself is certainly out of scope for routing-controllers

While it's a good idea it's place is in a different package not in routing-controllers. Maybe a routing-controllers CLI, (eg maybe in TypeStack?)

I think there's a lot we could do on the routing-controllers side to make projects more (easily) statically-analyzable by third-party tooling

Since type information is already there, the generator already can work if we would write one.

[adnan-kamili]

It would be great if it can automagically generate the Swagger docs. I feel at home using this great framework because of it's striking similarity with Asp.Net Core, but I am missing swagger gen middleware.

[github-actions[bot]]

Stale issue message