Why is Swagger/OpenAPI needed?

Question

RESTful API

Swagger/OpenAPI is a specification, i.e. just a REST API description format.
But how to use it?
1) Should the REST framework itself generate a yaml file describing the API?
2) Or vice versa, do we write a yaml file with our hands, on the basis of which some part of the code is generated?
For example, the need for this spec in scenario (1) is generally doubtful - I don’t need a yaml file, but a page of docks rendered in the browser - why do I need an intermediary in the form of this spec?
What generally use workflow?

Answer 1

There are several ways or approaches:
1) Yes, there are libraries (frameworks) that generate a specification file from the code, and from this file - documentation, for example, Swashbuckle , NSwag , etc. In this case, the developer just needs to use special framework tools (such as annotations) and the usual comments to the code, according to which the specification file will be generated and, after that, the documentation on it. That is, this file is not an intermediary, but a necessary "artifact", without it you still will not generate documentation.
In addition, using this generated file, it will already be possible to automatically generate client code in various programming languages. For example for C# and TypeScript using Unchase OpenAPI (Swagger) Connected Servicein the Visual Studio IDE 2017/2019, you can easily do this ( article on medium.com ).
2) Another approach involves first creating a specification file for the REST API (in yaml or json), and after generating both client code and service controller code from it (for example, both can be done using Unchase OpenAPI (Swagger) Connected Service ), as well as documentation. At the same time, the file itself does not have to be written by hand, there are constructors for OpenAPI services.
But writing a specification file by hand is convenient when the creation of a service is at the planning stage. If the service already exists, it is more convenient to use frameworks and constructors.