Convert swagger api documentation ( to slate static html page (
Clone or download
Latest commit 34e3192 Dec 19, 2016

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


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


Get slate in your repository

git clone --depth 1{your-name}/{your-repository} {your-repository}-docs # create folder to store docs
cd {your-repository}-docs
git remote add slate # 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/

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}{your-repository}/


Written with StackEdit.