From 034996f26551988e46486217fe246edf900b3906 Mon Sep 17 00:00:00 2001 From: Andrey Date: Wed, 15 Apr 2015 17:06:19 +0500 Subject: [PATCH 1/5] Update README.md --- README.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 62 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 8c9fdbd..f6d424d 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,74 @@ -Swagger to slate converter -========================== +# How to create html docs using swagger -## How to document your php api +* Store your api documentation with your code. +* Update and publish html documentation in couple lines in terminal. + +## 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](https://github.com/zircote/swagger-php/blob/2.x/docs/Getting%20started.md)) 4. Convert annotations to swagger.json (`./vendor/bin/swagger . -o ./swagger.json`) -5. Download swagger2slate ([Latest release](https://github.com/e96/swagger2slate/releases/latest)) -6. Convert swagger.json to slate markdown (`cat ./swagger.json | ./swagger2slate.phar > index.md`) -7. Use slate to generate static html documentation ([Getting Started with Slate](https://github.com/tripit/slate#getting-started-with-slate)) + +## Generate html docs and publish to github + +### Requirements +- empty branch gh-pages must exists +- swagger.json in repository +- [bundler](http://bundler.io) (`gem install bundler`) + +### Steps + +get slate in your repository +```shell +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 +```shell +bundle install --path vendor/bundle +echo -e "\nvendor/" >> .gitignore +``` + +Download [swagger2slate.phar](https://github.com/e96/swagger2slate/releases/latest) to current directory and set execution rights to file +```shell +chmod +x swagger2slate.phar +echo -e "\nswagger2slate.phar/" >> .gitignore +``` + +Generate slate markdown +```shell +cat ../{your-repository}/swagger.json | ./swagger2slate.phar > source/index.md +``` + +Preview docs +```shell +bundle exec middleman server +``` + +Commit changes +```shell +git add -u +git commit -m "api docs update" +``` + +Publish docs +```shell +bundle exec rake publish +``` + +Check out your doc: http://{your-name}.github.io/{your-repository}/ #### Resources * [Swagger specification 2.0](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md) * [Swagger explained](http://bfanger.github.io/swagger-explained) * [Doctrine annotations](http://doctrine-common.readthedocs.org/en/latest/reference/annotations.html) * [Swagger-php getting started](https://github.com/zircote/swagger-php/blob/2.x/docs/Getting%20started.md) -* [Slate](https://github.com/tripit/slate) \ No newline at end of file +* [Slate](https://github.com/tripit/slate) + +> Written with [StackEdit](https://stackedit.io/). From 3d9a0a7d45c373c4fc531781aec7cead07e0ca85 Mon Sep 17 00:00:00 2001 From: Andrey Date: Wed, 15 Apr 2015 17:07:55 +0500 Subject: [PATCH 2/5] Published with https://stackedit.io/ --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f6d424d..1e75564 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ ### Steps -get slate in your repository +Get slate in your repository ```shell git clone --depth 1 git@github.com:{your-name}/{your-repository} {your-repository}-docs # create folder to store docs cd {your-repository}-docs @@ -71,4 +71,4 @@ Check out your doc: http://{your-name}.github.io/{your-repository}/ * [Swagger-php getting started](https://github.com/zircote/swagger-php/blob/2.x/docs/Getting%20started.md) * [Slate](https://github.com/tripit/slate) -> Written with [StackEdit](https://stackedit.io/). +> Written with [StackEdit](https://stackedit.io/). \ No newline at end of file From d86e2f5243184f1ca4bcb1aac210116227ea4a21 Mon Sep 17 00:00:00 2001 From: Andrey Date: Wed, 15 Apr 2015 17:08:56 +0500 Subject: [PATCH 3/5] Published with https://stackedit.io/ --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 1e75564..d700e15 100644 --- a/README.md +++ b/README.md @@ -3,14 +3,14 @@ * Store your api documentation with your code. * Update and publish html documentation in couple lines in terminal. -## Document your php api +## 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](https://github.com/zircote/swagger-php/blob/2.x/docs/Getting%20started.md)) 4. Convert annotations to swagger.json (`./vendor/bin/swagger . -o ./swagger.json`) -## Generate html docs and publish to github +## 2. Generate html docs and publish to github ### Requirements - empty branch gh-pages must exists From 41eae2d8e84408178a5489450494b0439df0b4bc Mon Sep 17 00:00:00 2001 From: Andrey Date: Wed, 15 Apr 2015 17:09:32 +0500 Subject: [PATCH 4/5] Published with https://stackedit.io/ --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d700e15..549868e 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ ## 2. Generate html docs and publish to github ### Requirements -- empty branch gh-pages must exists +- branch gh-pages must exists - swagger.json in repository - [bundler](http://bundler.io) (`gem install bundler`) From 2c1029a24acff5b6ff582c03bfed36c5c03ac47f Mon Sep 17 00:00:00 2001 From: Andrey Date: Wed, 15 Apr 2015 17:35:52 +0500 Subject: [PATCH 5/5] Published with https://stackedit.io/ --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 549868e..7a8a039 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ echo -e "\nvendor/" >> .gitignore Download [swagger2slate.phar](https://github.com/e96/swagger2slate/releases/latest) to current directory and set execution rights to file ```shell chmod +x swagger2slate.phar -echo -e "\nswagger2slate.phar/" >> .gitignore +echo -e "\nswagger2slate.phar" >> .gitignore ``` Generate slate markdown