How to create html docs using swagger

• Store your api documentation with your code.
• Update and publish html documentation in couple lines in terminal.

1. Document your php api

1. Install Php annotations plugin for PhpStorm (Preferences → Plugins → Browse repositories → PHP Annotation → Install Plugin)
2. Install swagger-php (composer require zircote/swagger-php=2.*@dev)
3. Write annotations (Swagger-php getting started)
4. Convert annotations to swagger.json (./vendor/bin/swagger . -o ./swagger.json)

2. Generate html docs and publish to github

Requirements

• branch gh-pages must exists
• swagger.json in repository
• bundler (gem install bundler)

Steps

Get slate in your repository

git clone --depth 1 git@github.com:{your-name}/{your-repository} {your-repository}-docs # create folder to store docs
cd {your-repository}-docs
git remote add slate git@github.com:tripit/slate.git # add slate origin to pull from
git fetch slate
git checkout --orphan slate slate/master # create slate branch with slate/master contents
git commit -m "first slate commit"

Prepare slate

bundle install --path vendor/bundle
echo -e "\nvendor/" >> .gitignore

Download swagger2slate.phar to current directory and set execution rights to file

chmod +x swagger2slate.phar
echo -e "\nswagger2slate.phar" >> .gitignore

Generate slate markdown

./swagger2slate.phar convert ../{your-repository}/swagger.json  -o source/index.md

Preview docs

bundle exec middleman server

Commit changes

git add -u
git commit -m "api docs update"

Publish docs

bundle exec rake publish

Check out your doc: http://{your-name}.github.io/{your-repository}/

Resources

• Swagger specification 2.0
• Swagger explained
• Doctrine annotations
• Swagger-php getting started
• Slate

Written with StackEdit.