api_sketch 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2c2b16335a821956300f19937d9c5b64d4b2685d
-  data.tar.gz: 152e15df7c7030de612807127bc4ff3d3dcfa654
+  metadata.gz: 90161a84fafcc80e8b44bf641e4c40a865a22eed
+  data.tar.gz: 0642fda7b9fb81ab9802f2671d830871497a7e97
 SHA512:
-  metadata.gz: c2a10207ada23e6e82545cf29fa8483b179b29b12960ccf1baf41c5a358476fc2a2e185769ddfb48313aaf19fc624f11138d233cd8b146794ecda998e1b776ae
-  data.tar.gz: 4fa27b22d8c7dbf51ef822378bbba4fc5ed868cb5e3474c341c4a74797e7a64caf120b75951dab3305fdc36714f3bf9c22579833a9a6c1094e0480b30f6c7881
+  metadata.gz: 829d920527e420846256e6bf8ff95426da47b7c9c5ba2679a9bec20dc6a85cdf2a91ff30e77220a44bcf9ea40e44d4cf214b70db9e8a09d0cf3643fbb63bc646
+  data.tar.gz: 04df4fc5c7fd28268223ea6a6f28f457d9d3d4f62b33ac6509f21ad0c137826d8ce2198ccd4d52088fc2067a177d963072ce16c2f7f490421a9962c125adb031

data/.gitignore

@@ -7,6 +7,8 @@
 /pkg/
 /spec/reports/
 /tmp/
+.ruby-gemset
+.ruby-version
 *.bundle
 *.so
 *.o

data/CHANGELOG.md

@@ -1,4 +1,9 @@
-# 0.1.0 / 2015-05-03
+# 0.1.2 / 2015-05-31
+
+- Add `shared_block "shared block name"` (definition keyword) search keyword by it's to blocks. Keyword `use_shared_block "shared block name"` is used to find and use previously definded block. Shared blocks are be placed into special directory 'config/shared' at input folder to be loaded before all examples.
+- Reorganize internal gem structure.
+
+# 0.1.1 / 2015-05-03
 
 - Bootstrap template: put all generated pages data into `{output_folder}/docs` directory. Left `assets` directory outside since it may clash with generated files/folders names.
 - Add endpoint search by conjuction of request `path` & `http_method` for API examples server (Works like normal api server now).
@@ -12,4 +17,4 @@
 
 # 0.0.1 / 2015-01-24
 
-Initial release
+Initial release

data/README.md

@@ -107,12 +107,19 @@ Definitions
 
 API definitions files should be placed into directory with structure similar to `definitions` folder in this example. Directory may have only one file or many files and folders with files. Resurce's `namespace` is derived from this hierachical structure.
 
+`config` folder is loaded before `resources` folder. Some initial data as shared definition blocks may be placed at config folder.
+
 ```
 definitions
-├── places.rb
-├── users
-│   └── points.rb
-└── users.rb
+├── config
+│    └── initializers
+│         └── shared_blocks.rb
+│
+└── resources
+    ├── places.rb
+    ├── users
+    │   └── points.rb
+    └── users.rb
 ```
 ##### DSL
 
@@ -172,9 +179,7 @@ resource "Update user profile" do # Resource name
       integer "repeat_times" do
         description "times to repeat hello message"
       end
-    end
 
-    query :document do
       integer "page" do
         description "page number"
         required false
@@ -369,7 +374,57 @@ resource "Update user profile" do # Resource name
 end
 ```
 
-For more detailed DSL features examples check DSL test files at spec folder.
+For more detailed DSL features examples check DSL test files at `spec` and `examples` folders.
+
+#####DSL: Shared exmples
+
+This feature is designed to reduce definition duplications.
+Here is shared block definition example. It's defintion should be placed into `config` directory.
+
+```ruby
+shared_block "place fields" do
+  integer "id" do
+    description "Place database ID"
+  end
+
+  string "name" do
+    description "Place name"
+    example { ["Cafe", "Market", "Restaurant", "Parking", "Park", "Palace", "Stadium"].sample }
+  end
+
+  float "area" do
+    description "Place area in square meters"
+    example { rand(100) + rand.round(2) }
+  end
+end
+```
+
+Shared block usage example. Keyword `use_shared_block` is available at `headers`, `parameters`, `attributes` and `responses` definitions.
+
+```ruby
+resource "Get places list" do
+  action "index"
+  path "/api/places.json"
+  http_method "GET"
+  format "json"
+
+  responses do
+    context "Success" do
+      http_status :ok
+
+      parameters do
+        body :array do
+          document do
+            content do
+              use_shared_block "place fields"
+            end
+          end
+        end
+      end
+    end
+  end
+end
+```
 
 TODO
 ----
@@ -384,7 +439,6 @@ TODO
 - Add realtime viewable page with log for this api examples server application to let client side developers see what data they have sent and how server received it
 - Add more validations to models.
 - Add more specs and tests.
-- Add `shared_block "shared block name"` (definition keyword) search keyword by it's to blocks. Maybe `uses_shared_block "shared block name"`. Maybe shared blocks should be placed into special directory at definitions to be loaded before all examples
 - Add more complex example values autogeneration for API examples server. Derive values from key names. For example string "email" should have some email value as response example.
 - rDoc documentation for code.
 
@@ -408,4 +462,4 @@ Inspirations
 License
 -------
 
-ApiSketch is free software, and may be redistributed under the terms specified in the MIT-LICENSE file.
+ApiSketch is free software, and may be redistributed under the terms specified in the MIT-LICENSE file.

data/api_sketch.gemspec

@@ -12,7 +12,6 @@ Gem::Specification.new do |spec|
   spec.homepage      = "https://github.com/suhovius/api_sketch"
 
   spec.license       = "MIT"
-  spec.post_install_message = "Thanks for installing!"
 
   spec.files         = `git ls-files -z`.split("\x0")
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }

data/examples/api_project/config/initializers/shared_blocks.rb

@@ -0,0 +1,15 @@
+shared_block "place fields" do
+  integer "id" do
+    description "Place database ID"
+  end
+
+  string "name" do
+    description "Place name"
+    example { ["Cafe", "Market", "Restaurant", "Parking", "Park", "Palace", "Stadium"].sample }
+  end
+
+  float "area" do
+    description "Place area in square meters"
+    example { rand(100) + rand.round(2) }
+  end
+end

data/examples/api_project/resources/places.rb

@@ -0,0 +1,138 @@
+resource "Get place details" do
+  action "show"
+  description "Place details"
+  path "/api/places/:place_id.json"
+  http_method "GET"
+  format "json"
+
+  parameters do
+    query :array do
+      string do
+        description "place name"
+      end
+
+      integer do
+        description "search radius"
+      end
+    end
+  end
+
+  responses do
+    context "Success" do
+      http_status :ok # 200
+
+      parameters do
+        body :document do
+          use_shared_block "place fields"
+        end
+      end
+    end
+  end
+
+end
+
+resource "Create place" do
+  action "create"
+  path "/api/places.json"
+  http_method "POST"
+  format "json"
+
+  parameters do
+    body :document do
+      string "name" do
+        description "Place name"
+        example { ["Cafe", "Market", "Restaurant", "Parking", "Park", "Palace", "Stadium"].sample }
+      end
+
+      float "area" do
+        description "Place area in square meters"
+        example { rand(100) + rand.round(2) }
+      end
+    end
+  end
+
+  responses do
+    context "Success" do
+      http_status :ok # 200
+
+      parameters do
+        body :document do
+          use_shared_block "place fields"
+        end
+      end
+    end
+  end
+
+end
+
+
+resource "Update place" do
+  action "update"
+  path "/api/places/:place_id.json"
+  http_method "PUT"
+  format "json"
+
+  parameters do
+    body :document do
+      string "name" do
+        description "Place name"
+        example { ["Cafe", "Market", "Restaurant", "Parking", "Park", "Palace", "Stadium"].sample }
+      end
+
+      float "area" do
+        description "Place area in square meters"
+        example { rand(100) + rand.round(2) }
+      end
+    end
+  end
+
+  responses do
+    context "Success" do
+      http_status :ok # 200
+
+      parameters do
+        body :document do
+          use_shared_block "place fields"
+        end
+      end
+    end
+  end
+
+end
+
+resource "Get places list" do
+  action "index"
+  path "/api/places.json"
+  http_method "GET"
+  format "json"
+
+  parameters do
+    query :document do
+      integer "page" do
+        description "Pagination page"
+        default 1
+      end
+
+      integer "per_page" do
+        description "Pagination place per page"
+        default 25
+      end
+    end
+  end
+
+  responses do
+    context "Success" do
+      http_status :ok # 200
+
+      parameters do
+        body :array do
+          document do
+            content do
+              use_shared_block "place fields"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/examples/api_project/resources/users/points/stats.rb

@@ -0,0 +1,30 @@
+resource "Get user points stats" do
+  action "index"
+  description "User points stats"
+  path "/api/users/username/points/stats.json"
+  http_method "GET"
+  format "json"
+
+  responses do
+    context "Success" do
+      http_status :ok # 200
+
+      parameters do
+        body :document do
+          document "stats" do
+            content do
+              string "total" do
+                description "total amount"
+                example { rand(100) }
+              end
+              string "rank" do
+                description "user's rank"
+                example { ["Junior", "Middle", "Senior"].sample }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/examples/api_project/resources/users/points.rb

@@ -0,0 +1,32 @@
+resource "Get user points" do
+  action "index"
+  description "User points"
+  path "/api/users/username/points.json"
+  http_method "GET"
+  format "json"
+
+  responses do
+    context "Success" do
+      http_status :ok # 200
+
+      parameters do
+        body :array do
+          document do
+            content do
+              integer "items" do
+                description "user's items"
+                example { rand(1000) }
+              end
+
+              integer "rank" do
+                description "user's rank"
+                example { ["Test User", "Real User"].sample }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+
+end