Convert swagger api documentation ( to slate static html page (
Clone or download
Pull request Compare This branch is 2 commits ahead of E96:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

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.