Automatic documentation with Swagger or Swagger like solutions

[gabrieldocs]

About

In the last few months I've been working alongside two team that make use of Adonis 5 to develop some REST API's in addition to our ecosystem (mostly built around NodeJS and a few other API's built on top of PHP) and all other API's provide some sort ou integration with Swagger and follows the OpenAPI specification, but I've failed to find any similar solution.

I was wondering if you could provide some sort of orientation about this topic or, if there's something under development by the core team of Adonis, could you point any alpha/beta/experimental channels in what those resources are available?

References

The NestJS framework provides a recipe to include the Swagger via the @nestjs/swagger, as described in their documentation:
OpenAPI (Swagger)

The FastAPI framework comes with integration to Redoc and Swagger like described in their documentation: Extending OpenAPI

@thetutlage

[RomainLanz]

There is already a Swagger implementation for AdonisJS: https://github.com/reg2005/adonis5-swagger

[gabrieldocs]

I am already trying out this package, but the point I was making was about the need to manually write the API spec, what can introduce some sort of noise in the documentation if the file is not in sync or don't pass by the review or needed updates.

[CodeRogers]

This Swagger implementation is not automatic documentation, the point is that AdonisJS doesn't have an integration or implementation to easily document api routes and methods. This is useful to reduce the time spent writing each line in yml or json just to document the API methods and routes

[CodeRogers]

Another problem when using adonis5-swagger is that basePath doesn't seem to work. I've tried many ways to implement it, but I still have to write basePath on every route like: /api/v1/... and that doesn't seem to be very productive.

[thetutlage]

The main question is how good the auto generated API spec is? Here is an example hand-written API spec and I have not able to find a tool that can auto generate this by just looking at the code

[gabrieldocs]

I think this is exactly the point I was trying to make, so I appreciate the response. Right now I am looking for a better tool around this issue in order to produce less error/defects while providing some sort of documentation that can keep tracks of the code evolution and sync the documentation with no need for manual intervention, if not possible, the lesser manual intervention the better.

[gabrieldocs]

I think this is exactly the point I was trying to make, so I appreciate the response. Right now I am looking for a better tool around this issue in order to produce less error/defects while providing some sort of documentation that can keep tracks of the code evolution and sync the documentation with no need for manual intervention, if not possible, the lesser manual intervention the better.

@RomainLanz I think this resumes the point I was trying to make, the need for manual intervention on the specification which can lead to errors in the process.

[RomainLanz]

You used Nest as an example. You have to manually set all endpoints on Nest too.

[gabrieldocs]

Based on the current reply I think you misunderstood the question and how this NestJS package works. On NestJS we get to set the swagger tags or the API properties on the controllers and DTO's only if needed. The @nestjs/swagger still don't require me to write a spec file as prior to work as intended.

I tried to implement something with the package you suggested on the previous response and based on the contact I had with both frameworks this approach has shown to be much more susceptible to the introduction of errors and undesirable effects.

Some tool that could autogenerate this specs (or at least the specs yaml files) based on the current version of one's code with minimal intervention would be appreciated.

[lukfor85]

Hey folks, in another thread, I've asked about the possibility to make the model's serializable output strongly typed. Currently, due to serializeAs possible modification, it's not applicable, am I right?

I am elaborating on the integration of something like that: https://github.com/lukeautry/tsoa and that's probably what the author of this thread was looking for.

[stereobooster]

There are two approaches, depending on what is source of truth

• Code is source of truth - we generate swagger from code (this discussion)
• Swagger is source of truth - we generate code from swagger. See End-to-End TypeScript: Database, Backend, API, and Frontend #4017