If you are still not using a definition language for machine-readable API specifications, such as OpenAPI (formerly known as Swagger), you should definitely consider doing so. After all, APIs are languages for machines to talk to each other.

Is Swagger a good idea?

Swagger makes a very good first impression

Besides, many people think that the possibility to generate code out of the documentation is a good idea and Swagger provides that as well. So the fact that swagger makes a great first impression, makes its limitations and constraints less apparent.

What is the purpose of using Swagger?

Swagger allows you to describe the structure of your APIs so that machines can read them. The ability of APIs to describe their own structure is the root of all awesomeness in Swagger.