Created
July 12, 2016 09:51
-
-
Save ejhari/c8508caf98bd435bc7a61c6035ace713 to your computer and use it in GitHub Desktop.
REST API Documentation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| #! /bin/bash | |
| # | |
| # Currently using 'swagger' to create the api doc. | |
| # | |
| # REF: https://github.com/fsbahman/apidoc-swagger | |
| # REF: https://github.com/swagger-api/swagger-ui | |
| # | |
| # ################################################ | |
| # Instead, you could also use 'apidoc'. | |
| # REF: https://github.com/apidoc/apidoc | |
| # | |
| #./node_modules/apidoc/bin/apidoc -i src/ -o $ROOT | |
| # ################################################ | |
| echo " " | |
| echo " " | |
| echo " REST API Documentation. " | |
| echo " " | |
| echo " All rights reserved. " | |
| echo " " | |
| echo " " | |
| if [ `id -u` -ne 0 ] ; then | |
| echo "[!] Please run with sudo." | |
| exit | |
| fi | |
| if [ $1 = "-h" ] || [ $1 = "--help" ] || [ $# -lt 2 ] ; then | |
| echo "[!] Usage: sudo ./SERVE target-api-host target-api-port [target-api-basepath]" | |
| echo "[!] e.g. sudo ./SERVE localhost 9092 /api" | |
| exit | |
| fi | |
| echo "[-] Installing system deps..." | |
| if ! which git > /dev/null; then | |
| sudo apt-get install git | |
| fi | |
| # For Mac OS X. | |
| if which brew > /dev/null && ! which jq > /dev/null; then | |
| # We cannot brew as sudo. | |
| sudo -u $SUDO_USER brew install jq | |
| # For Linux. | |
| elif ! which jq > /dev/null; then | |
| sudo apt-get install jq | |
| fi | |
| sudo npm install | |
| ROOT="./doc" | |
| PORT=9876 | |
| echo "[*] Generating api documentation in $ROOT ..." | |
| API_HOST="$1" | |
| API_PORT="$2" | |
| if [ $3 ] ; then | |
| API_BASEPATH="$3" | |
| else | |
| API_BASEPATH="" | |
| fi | |
| echo "[*] Using API server at $API_HOST:$API_PORT$API_BASEPATH as target." | |
| if [ -f $ROOT/index.html ] && [ -f $ROOT/swagger-ui.js ]; then | |
| echo "[*] Existing UI assets found." | |
| else | |
| echo "[*] Cloning UI skeleton..." | |
| rm -rf $ROOT && git clone https://github.com/swagger-api/swagger-ui.git build | |
| cd build | |
| echo "[-] Installing UI deps..." | |
| sudo npm install | |
| echo "[-] Creating UI assets..." | |
| gulp | |
| cd .. | |
| mv build/dist $ROOT | |
| fi | |
| echo "[*] Generating conf file..." | |
| # Generate swagger json file . | |
| ./node_modules/apidoc-swagger/bin/apidocSwagger.js -i src -o build | |
| echo "[-] Sanitizing conf file..." | |
| # Add 'host' and 'basePath' fields to the generated swagger json. | |
| # The 'host' field is used as hostname for all the 'Try it out!' requests from | |
| # the UI. The 'basePath' field is used as prefix for the url given by the value | |
| # of above 'host' field. | |
| jq -c ".host = \"$API_HOST:$API_PORT\" | .basePath = \"$API_BASEPATH\"" build/swagger.json > $ROOT/swagger.json | |
| # Replace the default url 'http://petstore.swagger.io/v2/swagger.json' with | |
| # '/swagger.json' in place. | |
| # Otherwise we will have to pass the relative path of our custom swagger json file | |
| # as the value of url parameter. Refer $ROOT/index.html:36 . | |
| # Example: 'http://localhost:8080/index.html?url=/swagger.json'." | |
| sudo perl -p -i -e 's/url\s*=\s*\".*petstore\.swagger\.io.*swagger\.json\";/url = \"\/swagger\.json\";/g' $ROOT/index.html | |
| echo "[-] Cleaning up..." | |
| sudo rm -rf build | |
| echo "[*] Running doc server on port $PORT." | |
| cd $ROOT && python -m SimpleHTTPServer $PORT |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment