Swagger: How to Create an API Documentation

documentation is a vital part of any restful api and this is what we're going to create this is swagger UI it lists all the available rest endpoints and provides detailed information about them that description parameters output schema every endpoint can be tested this is useful both for API endpoints discovery and the development of the API building a documentation using swagger UI is possible thanks to a node.js module called swagger its main goal is to provide synchronization between the code of a node.js application and the documentation however a subset of its possibilities is useful for manually creating API documentation for any project regardless of the programming language used to create it swagger when installed globally provides an eponymous console script it accepts an array of commands two of which will be of use for us swagger Docs displays the specification of the open API standard used by swagger you can refer to this document when creating the documentation of your own API the other useful command is swagger project edit but before we can use it we need to trick swagger into believing it's editing an existing project since swagger forces a predefined directory structure let's create a configuration file in the location it will look in the file we need to create is API slash swagger slash swagger yamo this path is relative to the project route next let's paste in a minimal documentation if we don't swagger will fail to open the configuration file now we can start editing the documentation editing the documentation takes place in the browser on the left there is the documentation configuration removal on the right the documentation preview is updated as we edit the code any errors will be displayed here for quick recognition and fixing the edited Yama file is updated automatically but this isn't enough to display the documentation in swagger UI in order to do this we need to obtain the static files for the UI they can be found in the swagger UI package installable via NPM or Bower inside the package there is a directory named dist its contents are exactly what we need you when copied to the server static files directory the index.html file can be served displaying a sample documentation so far so good however the why relies on the JSON file not llamo we need to convert the document we created into the desired format an online service will do just fine for now you this works fine but we can do better than that first let's set the default URL opened by swaggy UI to our own documentation this line defines the default file opened we can change it to point to our api's documentation you we can also create a task that will convert the Yama into JSON for us it can be done in a variety of ways I will create a gulp task you this task makes use of an external dependency J SML to read the contents of the llamo file we created let's install it and test the task you in order to automate the conversion gulp can watch the changes in the saucy amo file you once the watch task is running any changes we make in the documentation editor will trigger the creation of the updated JSON file the changes in swag UI will be visible after reloading the page you I hope this has been useful to you if you liked this video give it a thumbs up and if you want to see more subscribe to my channel

Channel: Dominik Marczuk

Views: 370,259

Keywords: swagger, documentation, programming, api, rest

Id: xggucT_xl5U

Length: 7min 56sec (476 seconds)

Published: Sat Mar 12 2016