I use Swagger to document my APIs, since I really like the coupling of code & documentation. Also, the NodeJS Swagger-UI, which comes as an express middleware, is really easy to setup and run – bonus: the UI looks very nice!
To render the HTML docs, the Swagger-UI parses the
swagger.yaml file you have in your project. However, since also the version is hardcoded in the
swagger.yaml it has to be updated manually. How nice would it be if we could use the version specified in our
package.json and automatically update the yaml?
Try the script by calling
sh updateVersionInSwagger.sh in your project’s root dir and check the
swagger.yaml. All correct?
Now, of course you can trigger the script manually, but a more convenient way (which I also use) is to put it in the
version script of npm (see docs).
Since we would need the current version number while not yet adding a new git tag, especially the version-hook comes in handy:
Run the version script. These scripts have access to the new version in package.json (so they can incorporate it into file headers in generated files for example). Again, scripts should explicitly add generated files to the commit using git add. (cf. docs)
Finally, we need to add the hook in the
package.json as such:
"preversion": "sh doBranding.sh",
"version": "sh updateVersionInSwagger.sh && git add api/",
"postversion": "git push && git push --tags"
Now, you can try it yourself by just typing
npm version patch.