Skip to content

Instantly share code, notes, and snippets.

@danvine
Created April 19, 2014 15:20
Show Gist options
  • Save danvine/11087404 to your computer and use it in GitHub Desktop.
Save danvine/11087404 to your computer and use it in GitHub Desktop.
Simple bash workflow script for managing ever growing api documented using blueprintapi.org
#!/usr/bin/env bash
# Be sure to install the apiary gem; https://github.com/apiaryio/apiary-client
# gem install apiary
# You'll need to get a token here; https://login.apiary.io/tokens
APIARY_API_KEY=
# Your apiname here; docs.$APINAME.apiary.io
APINAME=
# Build your apib file from your nicely structured markdown directory
# Here is how mine looks,
# tree ./blueprint
# .
# ├── EXAMPLE.json
# ├── blueprint
# │   ├── 0_Intro.md
# │   ├── 1_FeatureA
# │   │   ├── 0_Intro.md
# │   │   ├── 1_Accounts.md
# │   ├── 2_FeatureB
# │   │   ├── 0_Intro.md
# │   │   ├── 1_Status.md
# ├── preview.sh
# ├── synthetic-with-comments.apib
# └── synthetic.apib
# Cleanup the temp files
rm ./_synthetic.apib 2> /dev/null
rm ./_synthetic-with-comments.apib 2> /dev/null
# Watch the sort on the find command
# This will dictate how the file is assembled
for MARKDOWN in $(find ./blueprint -type f -iname *.md | sort -u); do
# apiary rejects files with <!-- comments -->
# make sure they are on one line and this will strip them out.
# snowcrash is fine with comments oddly enough
#
cat "$MARKDOWN" | fgrep -v '<!--' >> ./_synthetic.apib
echo "" >> ./_synthetic.apib
# keep a copy with comments intact for debugging
#
cat "$MARKDOWN" >> ./_synthetic-with-comments.apib
echo "" >> ./_synthetic-with-comments.apib
done
# Verify synthetic file
snowcrash -v _synthetic-with-comments.apib
if [ $? -ne 0 ]; then
echo "ERROR: snowcrash says the synthetic file is invalid"
exit 1
fi
# Publish to apiary
apiary publish --path ./_synthetic.apib --api-name $APINAME
if [ $? -ne 0 ]; then
echo "ERROR: Apiary rejected the file"
exit 1
fi
# If we've gotten this far, the files are good
# You should be using git and feature branches or you risk losing your work
mv ./_synthetic.apib ./synthetic.apib
mv ./_synthetic-with-comments.apib ./synthetic-with-comments.apib
# Generate schema json
snowcrash synthetic.apib --output $APINAME.json 1> /dev/null 2> /dev/null
if [ $? -ne 0 ]; then
echo "ERROR: snowcrash couldn't generate schema file"
exit 1
fi
# Preview sexy 3 column documentation in your browser
open http://docs.$APINAME.apiary.io/?3ColumnDocumentation=1
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment