Up and Running With Swagger
Short description
- Install git (not covered in the article).
- Install anyenv.
- Install ndenv.
- Install nodejs.
- Install and configure the Swagger Editor.
- Build a simple demo API.
- Install and configure the Swagger tools.
- Deploy it to this site along with Swagger UI.
The details
Install anyenv:
git clone https://github.com/riywo/anyenv ~/.bash_profile
echo 'export PATH="$HOME/.anyenv/bin:$PATH"' >> ~/.bash_profile
echo 'eval "$(anyenv init -)"' >> ~/.bash_profile
exec $SHELL -l
Install ndenv:
anyenv install ndenv
exec $SHELL -l
Install nodejs:
ndenv install v0.12.7
exec $SHELL -l
ndenv install v0.12.7
Create a place to work:
mkdir swagger-demo && cd swagger-demo
Install and configure the Swagger Editor
git clone https://github.com/swagger-api/swagger-editor.git
cd swagger-editor
npm start
Since the build takes a while (even running the npm a second time), so I
checked the gruntjs task listing to look for a
“start server” task:
grunt --help
and found the serve task. So to restart the server:
grunt serve
then browse to http://localhost:9000 (if it doesn’t open automtically), and
edit the API until it is complete.
Next select the File / Download JSON, open the download directory and move
it to the proper location.
This demo will be displayed using the Swagger UI tool kit. I installed it using the Bower package management system.
bower install swagger-ui#2.1.1
This tooks some playing around with as some of the details aren’t explained very well on the Swagger UI home page or on the github page. Eventually I got it to look more or less correct by viewing the source of the Swagger Petstore online demo.
<link href='js/swagger-ui/dist/css/typography.css' media='screen' rel='stylesheet' type='text/css'/>
<link href='js/swagger-ui/dist/css/reset.css' media='screen' rel='stylesheet' type='text/css'/>
<link href='js/swagger-ui/dist/css/screen.css' media='screen' rel='stylesheet' type='text/css'/>
<link href='js/swagger-ui/dist/css/reset.css' media='print' rel='stylesheet' type='text/css'/>
<link href='js/swagger-ui/dist/css/print.css' media='print' rel='stylesheet' type='text/css'/>
<script src='js/swagger-ui/dist/lib/jquery-1.8.0.min.js' type='text/javascript'></script>
<script src='js/swagger-ui/dist/lib/jquery.slideto.min.js' type='text/javascript'></script>
<script src='js/swagger-ui/dist/lib/jquery.wiggle.min.js' type='text/javascript'></script>
<script src='js/swagger-ui/dist/lib/jquery.ba-bbq.min.js' type='text/javascript'></script>
<script src='js/swagger-ui/dist/lib/handlebars-2.0.0.js' type='text/javascript'></script>
<script src='js/swagger-ui/dist/lib/underscore-min.js' type='text/javascript'></script>
<script src='js/swagger-ui/dist/lib/backbone-min.js' type='text/javascript'></script>
<script src='js/swagger-ui/dist/swagger-ui.js' type='text/javascript'></script>
<script src='js/swagger-ui/dist/lib/highlight.7.3.pack.js' type='text/javascript'></script>
<script src='js/swagger-ui/dist/lib/marked.js' type='text/javascript'></script>
Where js/swagger-ui/dist/ is the dist directory in the bower download.
The swagger demo for the swagger JSON can be found here.
This took about 7 or 8 hours total to get this far. The Swagger Editor only took me about 45 minutes to get from nothing to fully operational. Getting the Swagger UI up and running (and discovering) what was avialable for a static website, took the rest of the time.