Updating Api Docs Web Page - groupon/backbeat GitHub Wiki

We are using a customized branch of swagger-ui to display our docs. Our branch of swagger-ui is located here . The server api docs are being statically served from aws. We use the grape-swagger gem along with a custom rake task to generate the swagger json files which our swagger ui branch uses.

Updating the api doc web page

After making changes to the api docs in the backbeat server source code, you will probably want to update the docs on the web page. Follow these instructions to do so

Update the api version constant if necessary. (Backbeat::VERSION)
Run the rake task in your backbeat server repo and set the base-url variable to the url of running backbeat server that you want to generate docs off of.(default is localhost:9292)
```
bundle exec rake swagger:generate base-url=<your_backbeat_server_url> 
```
Take the generated folder (should be the number of the backbeat version) and put it the /api-versions folder in your local branch of the custom swagger-ui repo. Make sure you have the swagger-ui repo dependencies installed as per the swagger-ui repo's README.
If you are adding a new version of api docs, and not just updating an already existing version's docs, add the new version to the available_versions array in the index.html file and make sure it matches the name of the folder you added in step 3.
```
i.e. var available_versions = ["1.0", "2.0"];
```

You can test your changes locally by running

gulp

cd dist

python -m SimpleHTTPServer 8000

and checkout your changes in a browser at 0.0.0.0:8000 6. To deploy your changes of the ui, copy the contents of the dist folder to where you want to serve the static docs page. Make sure you have cors enabled for swagger-ui to work. Currently the UI for the api docs is hosted here http://backbeatdocumentation.s3-website-us-west-2.amazonaws.com/. Contact [email protected] for the time being if you want it deployed to that location.