Document Entity enums values (#21)

bsm · Oct 4, 2021 · cd319df · cd319df
1 parent 90f3ccf
commit cd319df
Show file tree

Hide file tree

Showing 3 changed files with 23 additions and 19 deletions.
diff --git a/lib/grape/apidoc.rb b/lib/grape/apidoc.rb
@@ -3,7 +3,8 @@ class Apidoc
     autoload :RakeTask, 'grape/apidoc/rake_task'
     autoload :TableFormat, 'grape/apidoc/table_format'
 
-    FIELDS_TABLE = TableFormat.new([20, 10, 40]).freeze # Field, Type, Description
+    ENTITY_FIELDS_TABLE = TableFormat.new([20, 10, 30, 10]).freeze # Field, Type, Description, Values
+    ROUTE_FIELDS_TABLE = TableFormat.new([20, 10, 40]).freeze # Field, Type, Description
 
     def initialize(root_api_class = nil, output: $stdout)
       @api = root_api_class || detect_root_api_class
@@ -75,13 +76,13 @@ def write_entity_fields!(entity)
         return
       end
 
-      @out.puts FIELDS_TABLE.format('Field', 'Type', 'Description')
-      @out.puts FIELDS_TABLE.separator
+      @out.puts ENTITY_FIELDS_TABLE.format('Field', 'Type', 'Description', 'Values')
+      @out.puts ENTITY_FIELDS_TABLE.separator
 
       entity.root_exposures.each do |exposure|
         name = exposure.key
         doc = entity.documentation[name] || {}
-        type, desc, = doc.values_at(:type, :desc)
+        type, desc, vals = doc.values_at(:type, :desc, :values)
 
         # fall back to `using:...`
         unless type
@@ -93,7 +94,7 @@ def write_entity_fields!(entity)
         end
 
         type = "[#{type}]" if doc[:is_array]
-        @out.puts FIELDS_TABLE.format(name.to_s, type.to_s, desc.to_s)
+        @out.puts ENTITY_FIELDS_TABLE.format(name.to_s, type.to_s, desc.to_s, vals&.join(', '))
       end
     end
 
@@ -153,8 +154,8 @@ def write_route_params!(route)
       @out.puts '**Parameters**:'
       @out.puts
 
-      @out.puts FIELDS_TABLE.format('Parameter', 'Type', 'Description')
-      @out.puts FIELDS_TABLE.separator
+      @out.puts ROUTE_FIELDS_TABLE.format('Parameter', 'Type', 'Description')
+      @out.puts ROUTE_FIELDS_TABLE.separator
 
       route.params.each do |name, doc|
         # route.params includes path params as well, like `id => ''`
@@ -166,7 +167,7 @@ def write_route_params!(route)
         # Need to either enforce some requirements for organizing API or give up.
         type = doc[:type] || ''
         desc = doc.except(:type).map {|k, v| "#{k}: #{v}" }.join(', ')
-        @out.puts FIELDS_TABLE.format(name.to_s, type, desc)
+        @out.puts ROUTE_FIELDS_TABLE.format(name.to_s, type, desc)
       end
     end
 

diff --git a/spec/fixtures/example.md b/spec/fixtures/example.md
@@ -2,22 +2,23 @@
 
 ## Example:Role
 
-| Field                | Type       | Description                              |
-| -------------------- | ---------- | ---------------------------------------- |
-| code                 | String     | Role Code/Name                           |
+| Field                | Type       | Description                    | Values     |
+| -------------------- | ---------- | ------------------------------ | ---------- |
+| code                 | String     | Role Code/Name                 |            |
+| level                | String     | Role Access Level              | 1, 2, 3    |
 
 ## Example:User
 
-| Field                | Type       | Description                              |
-| -------------------- | ---------- | ---------------------------------------- |
-| email                | String     | User Email                               |
+| Field                | Type       | Description                    | Values     |
+| -------------------- | ---------- | ------------------------------ | ---------- |
+| email                | String     | User Email                     |            |
 
 ## Example:User:Full
 
-| Field                | Type       | Description                              |
-| -------------------- | ---------- | ---------------------------------------- |
-| email                | String     | User Email                               |
-| roles                | [[Example:Role](#examplerole)] | User Roles                               |
+| Field                | Type       | Description                    | Values     |
+| -------------------- | ---------- | ------------------------------ | ---------- |
+| email                | String     | User Email                     |            |
+| roles                | [[Example:Role](#examplerole)] | User Roles                     |            |
 
 # Routes
 
@@ -48,3 +49,4 @@ Update User
 | roles                | [JSON]     | required: false                          |
 | roles[name]          | String     | required: true                           |
 | email                |            |                                          |
+
diff --git a/spec/scenario/example.rb b/spec/scenario/example.rb
@@ -1,9 +1,10 @@
 module Example
-  Role = Struct.new(:name)
+  Role = Struct.new(:name, :level)
   User = Struct.new(:email, :roles)
 
   class Role::Entity < Grape::Entity
     expose :name, as: :code, documentation: { type: 'String', desc: 'Role Code/Name' }
+    expose :level, documentation: { type: 'String', desc: 'Role Access Level', values: [1, 2, 3] }
   end
 
   class User::Entity < Grape::Entity