DEV Community

Discussion on: Why use Swagger for creating and documenting APIs

Collapse
 
millebi profile image
Bill Miller

A few thoughts that may be helpful:

I'm not sure if the newest version is the same (I assume it is), but the older version of Swagger allowed for dynamic generation of your API as well as a static (compile time) version.

The dynamic version essentially creates an API to call your API at runtime, but it is also running code inside your server... which may/may not be a security/performance problem for your application.

The static version generates the needed files during compile and the files are then deployed using simple HTML deployment. This makes them simpler to deploy and not have any extra security/performance risks to your application (other than serving the files of course).

The two methods of deployment end up having implied features not explicity defined by the authors, like:

  • Dev/QA: Dynamic publishing of the API, so that it is always accurate.
  • Production: Static publishing of your API to reduce risk AND control which features you want to advertise to callers (i.e. Display a subset of what's actually available until new features are fully tested and scaled)

Mixing the two types depending on the context can be extremely useful and have the same upfront "costs" to implement (i.e. The information entered into the code is the same for both methods).