Skip to content

Latest commit

 

History

History
74 lines (58 loc) · 2.34 KB

README.md

File metadata and controls

74 lines (58 loc) · 2.34 KB
Raw

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

Written with StackEdit.