apipony 0.0.9 → 1.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7456f0b6bcd79edd941bfba6e1db27e3c0b94f00
-  data.tar.gz: 08f3bb7e4dfdb5a590a78f8ed2be46b5a475e873
+  metadata.gz: c2763c3a557bf3218d2e22427926fa6ccac254a8
+  data.tar.gz: 4684d6258f0a056d13b33dc189c48cb9de433da9
 SHA512:
-  metadata.gz: d8a9c0b84b6da18245b2dc3187a63ee8ad30de426d45a4fd47f2ee7e384405dd1e4a2665358f0df09b214804157afaa09d0a5c6c2c2410120782c281bfdb79ff
-  data.tar.gz: 4d7d48df1304b3e316adc35e410ae44f040195127e9dfcd4dca971c6c2dcd806d737ee0ceb31a68c1fd3173b1884333da21b02989c97a252f8390ce8fc45c2c1
+  metadata.gz: aa6373f944c15dfcb256dd1a22889426bd6936698733db49285a25d41b5a3eca71125e0f52a683fcbcd16889fae92ca02ed12169027ff01459c6d3fc78cd5f7b
+  data.tar.gz: a19bc419ba2fc6bcf86a761bf1710070fc7193ebd65307b68778e877ed2a211b88131a76092633fc405e959c7af7ac25798ea2c199fb0321272dfe0e00da9503

data/README.md

@@ -6,246 +6,124 @@
 
 Ruby DSL to create Rails API documentation from your application.
 
-
-## Getting started
+## Getting Started
 * Add `gem 'apipony'` to Gemfile
 * `bundle install`
 * `rails g apipony:install`
-* Now you can edit your documentation in `config/initializers/apipony.rb`
+* Edit your documentation in `config/initializers/apipony.rb`
 
+![Example](https://raw.githubusercontent.com/droptheplot/apipony/master/preview.png)
 
-## How it works
-DSL example:
+## Example
 
 ```ruby
 Apipony::Documentation.define do
-  config do |c|
-    c.title = 'Apipony Documentation'
-    c.base_url = '/api/v1'
+  configure do
+    title 'API Documentation'
+    base_url '/api/v1'
   end
 
   section 'Ponies' do
-    endpoint :get, '/ponies' do |e|
-      e.description = 'Find ponies'
+    endpoint :get, '/ponies' do
+      description 'List ponies.'
 
       request_with do
-        param :name, example: 'applejack', required: true
-      end
+        headers do
+          {
+            'Accept': 'application/json'
+          }
+        end
 
-      response_with 200 do
-        attribute :name, type: :string, example: 'applejack'
-        attribute :kind, type: :string, example: 'earth'
-        attribute :sex, type: :string, example: 'female'
-        attribute :occupation, type: :string, example: 'farmer'
+        param :name, required: true, description: 'Name of pony.',
+                                     example: :fluttershy
       end
-    end
-  end
-end
-```
-
-
-## Features
 
-### Response Attribute Documentation
-Apipony lets you provide further documentation about the attributes in your
-API's responses. Simply create a new `attribute` inside a `response_with` block.
-These attributes can even have nested sub-attributes, for documentation of
-more complex object graphs.
-
-```ruby
-Apipony::Documentation.define do
-  section "Species" do
-    endpoint 'get', '/species/:id' do |e|
-      e.description = "Get information about a species"
-      response_with 200 do
-        example do
-          set :body, {
-            name: "Unicorn",
-            is_pony: true,
-            biology: {
-              has_horn: true,
-              has_wings: false
+      response_with do
+        body do
+          [
+            {
+              name: 'Fluttershy',
+              kind: 'Pegasus'
             }
-          }
-        end
-        attribute :name, type: :string
-        attribute :is_pony, type: :bool,
-          description: "Is this species a type of pony?"
-        attribute :biology do
-          attribute :has_horn, type: :bool
-          attribute :has_wings, type: :bool
+          ]
         end
       end
     end
-  end
-end
-```
 
-### Enum Attributes
-Your API may have some fields that can be picked from a pre-defined set of
-values. You can document those values by using an enum attribute.
+    endpoint :post, '/ponies' do
+      description 'Create new pony.'
 
-```ruby
-Apipony::Documentation.define do
-  section "Ponies" do
-    endpoint "get", "/ponies/:id" do |e|
-      e.description = "Information about a pony"
-      example do
-        set :body, {
-          name: "Applejack",
-          sex: "female",
-          kind: :earth,
-          occupation: :farmer
-        }
-      end
-
-      attribute :kind, type: :enum do
-        choice :earth, description: "A pony with no wings or horn"
-        choice :unicorn, description: "A pony with a horn"
-        choice :pegasus, description: "A pony with wings"
-        choice :alicorn,
-          description: "A pony with wings and a horn. Indicates royalty."
+      request_with do
+        param :name, required: true, example: :fluttershy
+        param :kind, example: :pegasus
+        param :sex, required: true, example: :female
+        param :occupation, example: :caretaker,
+                           description: 'What this pony do for living.'
       end
     end
-  end
-end
-```
 
-### Example Generation
-When describing attributes, you can provide an optional `example:` parameter.
-If included, this will be used to generate the example response in the
-documentation.
+    endpoint :put, '/ponies/:id' do
+      description 'Update pony by id.'
 
-```ruby
-Apipony::Documentation.define do
-  section "Ponies" do
-    endpoint "get", "/ponies/:id" do |e|
-      response_with 200 do
-        attribute :name, type: :string, example: "Applejack"
-        # Enum members automatically select the first choice
-        attribute :kind, type: :enum do
-          choice :earth
-          choice :pegasus
-          choice :unicorn
-          choice :alicorn
-        end
+      request_with do
+        param :name
+        param :kind
+        param :sex
+        param :occupation
       end
     end
 
-    endpoint "get", "/ponies/" do |e|
-      # Automatic serialization of arrays is supported
-      response_with 200, array: true do
-        attribute :name, type: :string, example: "Applejack"
-        attribute :id, type: :integer, example: 10
-      end
+    endpoint :delete, '/ponies/:id' do
+      description 'Delete pony by id.'
     end
   end
-end
-```
-
-`GET /ponies/:id` will now have the example of:
-
-```json
-{
-  "name": "Applejack",
-  "kind": "Earth"
-}
-```
-
-`GET /ponies/` will have the example of:
-
-```json
-[
-  {
-    "name": "Applejack",
-    "id": 10
-  }
-]
-```
 
-### Predefined Subtypes
-Sometimes, when building an API, it can be useful to store data in a common
-format. Apipony lets you define this common format once, then use it multiple
-times. Check it out:
+  section 'Places' do
+    endpoint :get, '/places' do
+      description 'List places.'
 
-```ruby
-Apipony::Documentation.define do
-  subtype :pony_stub do
-    attribute :name, type: :string
-    attribute :id, type: :integer
-  end
+      response_with do
+        status 200
 
-  section "Ponies" do
-    endpoint 'get', '/ponies/:id' do |e|
-      e.description = "Find a pony with a given name"
-      request_with do
-        params :id, example: 10, required: true
-      end
-
-      response_with 200 do
-        example do
-          set :body, {
-            :name => :applejack,
-            :type => :earth,
-            :sex => :female,
-            :occupation => :farmer,
-            :friends => [
-              {name: "Twilight Sparkle", id: 1},
-              {name: "Pinkie Pie", id: 2},
-              {name: "Rainbow Dash", id: 3},
-              {name: "Rarity", id: 4},
-              {name: "Fluttershy", id: 5}
-            ]
-          }
+        body do
+          [
+            {
+              name: 'Equestria'
+            },
+            {
+              name: 'Ponyville'
+            }
+          ]
         end
-      attribute :name, type: :string
-      attribute :kind, type: :enum do
-        choice :alicorn
-        choice :earth
-        choice :unicorn
-        choice :pegasus
       end
-      attribute :friends, type: :pony_stub, array: true
-      attribute :occupation, type: :string
     end
-  end
 
-  section "Locations" do
-    endpoint 'get', '/locations/:id' do |e|
-      e.description = "Information about a location"
-      response_with 200 do
-        example do
-          set :body, {
-            :name => "Crystal Empire",
-            :population => 107770,
-            :rulers => [
-              {
-                name: "Shining Armor",
-                id: 50
-              },
-              {
-                name: "Princess Cadence",
-                id: 90001
-              }
-            ]
+    endpoint :get, '/places/:id' do
+      response_with do
+        status 200
+
+        body do
+          {
+            name: 'Crystal Empire',
+            population: 107706
           }
         end
-        attribute :name, type: :string
-        attribute :population, type: :integer
-        attribute :rulers, type: :pony_stub, array: true
       end
     end
   end
 end
 ```
 
-Now, the `friends` attribute of `GET /ponies/:id` and the `rulers` attribute of
-`GET /locations/:id` will reference a common subtype on the generated
-documentation.
+By default documentation available here `/apipony`. But you can always change it in `config/routes.rb`.
 
+## Contributing
 
-Generated documentation example:
+1. Fork it (https://github.com/droptheplot/apipony/fork)
+2. Create your feature branch (git checkout -b my-new-feature)
+3. Commit your changes (git commit -am 'Add some feature')
+4. Push to the branch (git push origin my-new-feature)
+5. Create new Pull Request
 
-![Example](https://raw.githubusercontent.com/droptheplot/apipony/master/preview.png)
+## License
 
-By default documentation available here `/apipony`. But you can always change it in `config/routes.rb`.
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -7,17 +7,13 @@ end
 
 require 'rdoc/task'
 
-YARD::Rake::YardocTask.new(:doc) do |doc|
-end
-
-APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
-load 'rails/tasks/engine.rake'
+YARD::Rake::YardocTask.new(:doc) {}
 
+APP_RAKEFILE = File.expand_path('../spec/dummy/Rakefile', __FILE__)
 
+load 'rails/tasks/engine.rake'
 load 'rails/tasks/statistics.rake'
 
-
-
 Bundler::GemHelper.install_tasks
 
 require 'rake/testtask'
@@ -29,5 +25,4 @@ Rake::TestTask.new(:test) do |t|
   t.verbose = false
 end
 
-
 task default: :test

data/app/assets/stylesheets/apipony/styles.scss

@@ -5,14 +5,14 @@ $light_color: #eee;
 $brand_color: #5e147d;
 
 // Method colors
-$get-color: #1abc9c;
-$post-color: #3498db;
-$put-color: #2980d9;
-$delete-color: #c0392b;
+$get_color: #1abc9c;
+$post_color: #3498db;
+$put_color: #2980d9;
+$delete_color: #c0392b;
 
 // Misc. values
-$transition-time: 200ms;
-$mobile-width: 900px;
+$transition_time: 200ms;
+$mobile_width: 900px;
 
 
 *, *::before, *::after {
@@ -57,7 +57,7 @@ h2 {
 }
 
 h3 {
-  padding-top: 10px;
+  margin-bottom: 20px;
   font-size: 17px;
   line-height: 16px;
 }
@@ -96,7 +96,7 @@ ul {
   display: flex;
   flex-flow: row nowrap;
 
-  @media all and (max-width: $mobile-width) {
+  @media all and (max-width: $mobile_width) {
     flex-flow: row wrap;
   }
 }
@@ -105,7 +105,7 @@ ul {
   flex: 1 80px;
   margin-right: 40px;
 
-  @media all and (max-width: $mobile-width) {
+  @media all and (max-width: $mobile_width) {
     flex: 1 100%;
     margin-bottom: 30px;
   }
@@ -120,28 +120,27 @@ ul {
 .main-col {
   flex: 8;
 
-  @media all and (max-width: $mobile-width) {
+  @media all and (max-width: $mobile_width) {
     flex: 1 100%;
   }
 }
 
 header {
-  background: $brand_color;
   height: 60px;
   line-height: 60px;
+  border-bottom: 1px solid $light_color;
 
   .title {
     font-weight: bold;
-    font-size: 20px;
-    color: #fff;
+    font-size: 17px;
   }
 
   .back {
     float: right;
-    color: #fff;
     opacity: 0.7;
     font-size: 12px;
-    transition: $transition-time opacity;
+    transition: $transition_time opacity;
+    margin-left: auto;
 
     &:hover {
       opacity: 1;
@@ -163,7 +162,7 @@ footer {
 
   a {
     color: $medium_color;
-    transition: $transition-time color;
+    transition: $transition_time color;
 
     &:hover {
       color: $dark-color;
@@ -185,23 +184,23 @@ footer {
       margin-bottom: 40px;
     }
 
-    .description {
-      font-size: 12px;
-      color: $medium_color;
-      padding-top: 20px;
-      font-weight: normal;
-    }
-
     .response, .request {
-      padding-top: 20px;
+      padding-bottom: 20px;
 
       .code {
         padding: 8px 10px 10px;
-        font-size: 14px;
+        font-size: 12px;
         border-radius: 0 0 3px 3px;
       }
     }
   }
+
+  > .description, .endpoint > .description {
+    font-size: 12px;
+    color: $medium_color;
+    padding-bottom: 20px;
+    font-weight: normal;
+  }
 }
 
 .panel {
@@ -230,23 +229,23 @@ footer {
   background-color: $medium_color;
 
   &.get {
-    background-color: $get-color;
+    background-color: $get_color;
   }
 
   &.post {
-    background-color: $post-color;
+    background-color: $post_color;
   }
 
   &.put {
-    background-color: $put-color;
+    background-color: $put_color;
   }
 
   &.delete {
-    background-color: $delete-color;
+    background-color: $delete_color;
   }
 }
 
-.parameters, .attributes {
+.parameter {
   font-size: 12px;
 
   .name {
@@ -266,6 +265,12 @@ footer {
       color: $medium_color;
     }
   }
+
+  > .description {
+    .example {
+      color: $medium_color;
+    }
+  }
 }
 
 .table {
@@ -277,72 +282,3 @@ footer {
     }
   }
 }
-
-.attribute-container {
-  display: flex;
-  flex-flow: column nowrap;
-
-  .attribute {
-    display: flex;
-    flex-flow: row nowrap;
-    align-items: inherit;
-    justify-content: flex-start;
-
-    > div {
-      padding: 4px 10px;
-    }
-
-    .attribute-type {
-      flex: 1 1 60px;
-    }
-
-    .attribute-name {
-      flex: 2 1 0;
-      min-width: 90px;
-    }
-
-    .attribute-description {
-      flex: 8 1 0;
-    }
-  }
-
-  ul {
-    margin: 8px 10px;
-    border: 1px solid #e1e1e1;
-    border-radius: 3px;
-
-    li {
-      list-style: none;
-      margin: 10px 0;
-      padding: 0 12px;
-    }
-  }
-}
-
-.attribute-enum-member {
-  display: flex;
-  flex-flow: row nowrap;
-
-  .title {
-    border-bottom: 1px solid darken($light_color, 5%);
-    padding: 10px;
-    font-size: 11px;
-    font-weight: bold;
-  }
-
-  .attribute-enum-member-name {
-    font-weight: 400;
-    margin-right: 10px;
-    min-width: 60px;
-    flex: 1 1 0;
-    color: $brand_color;
-  }
-
-  .attribute-enum-member-description {
-    flex: 7 1 0;
-  }
-}
-
-.subtype {
-  margin-bottom: 25px;
-}

data/app/views/apipony/application/_header.html.erb

@@ -1,8 +1,13 @@
 <header>
   <div class="container">
-    <%= link_to @documentation.title, root_path, class: 'title' %>
-    <% if main_app.root_path %>
-      <%= link_to 'Back to site', main_app.root_path, class: 'back' %>
-    <% end %>
+    <div class="row">
+      <%= link_to @documentation.data.title, root_path, class: 'title' %>
+      <% if main_app.root_path %>
+        <%= link_to main_app.root_path, class: 'back' do %>
+          <i class='fa fa-home'></i>
+          Home
+        <% end %>
+      <% end %>
+    </div>
   </div>
 </header>

data/app/views/apipony/application/_request.html.erb

@@ -1,11 +1,19 @@
 <div class="request">
   <h4>Request&#58;</h4>
-  <% if endpoint.request.params %>
+
+  <% if endpoint.request.data.headers %>
+    <div class="panel">
+      <div class="title">Headers</div>
+      <pre class="code"><%= JSON.pretty_generate(endpoint.request.data.headers) %></pre>
+    </div>
+  <% end %>
+
+  <% if endpoint.request.data.params %>
     <div class="panel">
       <div class="title">Parameters</div>
       <table class="table">
-        <% endpoint.request.params.each do |param| %>
-          <tr class="parameters">
+        <% endpoint.request.data.params.each do |param| %>
+          <tr class="parameter">
             <td class="name">
               <%= param.name %>
             </td>
@@ -19,19 +27,17 @@
                 <i class="fa fa-square-o" title="Optional"></i>
               <% end %>
             </td>
-            <td class="example">
-              <%= param.example %>
+            <td class="description">
+              <%= param.description %>
+              <% if param.example %>
+                <span class="example">
+                  (example: <strong><%= param.example %></strong>)
+                </span>
+              <% end %>
             </td>
           </tr>
         <% end %>
       </table>
     </div>
   <% end %>
-
-  <% if endpoint.request.headers %>
-    <div class="panel">
-      <div class="title">Headers</div>
-      <pre class="code"><%= JSON.pretty_generate(endpoint.request.headers) %></pre>
-    </div>
-  <% end %>
 </div>