- Store your api documentation with your code.
- Update and publish html documentation in couple lines in terminal.
- Install Php annotations plugin for PhpStorm (Preferences → Plugins → Browse repositories → PHP Annotation → Install Plugin)
- Install swagger-php (
composer require zircote/swagger-php=2.*@dev) - Write annotations (Swagger-php getting started)
- Convert annotations to swagger.json (
./vendor/bin/swagger . -o ./swagger.json)
- branch gh-pages must exists
- swagger.json in repository
- bundler (
gem install bundler)
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/" >> .gitignoreDownload swagger2slate.phar to current directory and set execution rights to file
chmod +x swagger2slate.phar
echo -e "\nswagger2slate.phar" >> .gitignoreGenerate slate markdown
./swagger2slate.phar convert ../{your-repository}/swagger.json -o source/index.mdPreview docs
bundle exec middleman serverCommit changes
git add -u
git commit -m "api docs update"Publish docs
bundle exec rake publishCheck out your doc: http://{your-name}.github.io/{your-repository}/
Written with StackEdit.