grape_openapi3 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c028381878b52f6a689b843e5e0b4aa37799bc26fc612316b51a6617783f4afa
-  data.tar.gz: b72d1e69efff1e6575cb72c2d1fae4c2a09d5a908f5e809a7c3b8303f681c4b8
+  metadata.gz: 567bc33ad5a25000b165090cc8defe1d5e819fb6c8a5df0cccbab2dddb27cca4
+  data.tar.gz: 74bebc4d7030935208f01fb429362b26041522f7616d3949e02a9d5b8a104765
 SHA512:
-  metadata.gz: 7908a7ac38deeeda95246ee30026f82b9f3c872ff26c4c8863de6b2f9a6157963d5230235bc616593b761603ce3291ee4608711417e88085ff5430f99e4f6c17
-  data.tar.gz: '089da884741c789d424e8e11f55814b20ef2025567ba08b9c9f4a7231e4980fd306d5e6d621b8fcec1490faa0bcedc278b4b1325a1696a627966ae650d44316a'
+  metadata.gz: 1c640016dab4cb6e03d32bc9af02c3d3a22ea060ed94a3cbe6bdabbc83e423a6a0df01211460567ea155091b23ae031093ef979f1f878d770df5f560470e6ae0
+  data.tar.gz: 67ebcdac076ec212d794ca4aae5f7ecf4ddcdc1640557e9c63652dfe44af345407ae5c7558c4edf61e60d6cb5f49151cbdfe6ef0fdb31473e949f8332b268fd3

data/README.md

@@ -107,6 +107,24 @@ success: { code: 200, message: "Done." }
 success: { code: 201, model: Entities::ProductEntity, message: "Product created." }
 ```
 
+### Failure options (typed error responses)
+
+Error responses can carry a schema too — point them at a `Grape::Entity` with
+`model:` (or an inline OpenAPI schema with `schema:`). Without either, a failure
+stays a plain description.
+
+```ruby
+failure: [
+  { code: 401, message: "Unauthorized" },                                  # description only
+  { code: 404, message: "Not found",   model: Entities::ErrorEntity },     # $ref to a schema
+  { code: 422, message: "Validation",  model: Entities::ValidationErrorEntity },
+  { code: 409, message: "Conflict",    schema: { type: "object", properties: { code: { type: "string" } } } },
+]
+```
+
+This lets an OpenAPI → TypeScript/Zod codegen type your error payloads, not just
+the success body.
+
 ### Params via params do block
 
 ```ruby
@@ -244,24 +262,52 @@ Rails serves `public/` as static files automatically. Navigate to `http://localh
 
 ## Example project
 
-The `example/rails_app/` folder contains a full Rails 8 + Grape API with a products CRUD — the same setup described in this README, ready to run:
+The `example/rails_app/` folder is a complete, runnable **Rails 8 + Grape** API you
+can use to see everything in action. It models a small real-world domain:
+
+- **`Product`** — CRUD resource (`/api/v1/products`)
+- **`Category`** — `Product belongs_to :category`, exposed as a **nested entity**
+- **Typed errors** — `404`/`422` responses carry `ErrorEntity` / `ValidationErrorEntity`
+- **Live docs** — the OpenAPI JSON is served dynamically by a mounted endpoint
+  (`V1::OpenapiDoc`), no build step required
+
+### Run it
 
 ```bash
 cd example/rails_app
 bundle install
-rails db:create db:migrate db:seed
-rails server
+bin/rails db:prepare        # create + migrate + seed (5 categories, 20 products)
+bin/rails server
+```
 
-# API live at:
-#   http://localhost:3000/api/v1/products
+### What to open
 
-# Generate the docs:
-bundle exec rake openapi:generate
+| URL | What you get |
+|---|---|
+| `http://localhost:3000/swagger.html` | **Swagger UI** — browse and try every endpoint |
+| `http://localhost:3000/api/v1/openapi` | the **OpenAPI 3.0 JSON**, generated live from the routes |
+| `http://localhost:3000/api/v1/products` | the actual API — note `category` comes back as `{ id, name }` |
+
+### Things to notice in the docs
+
+- `ProductEntity.category` is a `$ref` to `CategoryEntity` (the `belongs_to`).
+- `POST /api/v1/products` shows the `404`/`422` responses with **typed bodies**.
+- Edit an entity or route, refresh `/swagger.html` — the doc updates immediately
+  (it's generated per request; no rake step needed).
 
-# View Swagger UI:
-#   http://localhost:3000/swagger.html
+### Static doc (optional)
+
+If you'd rather serve a static file (e.g. for hosting), there's also a rake task:
+
+```bash
+bundle exec rake openapi:generate           # writes public/openapi.json
+OPENAPI_SERVER_URL=https://api.example.com/api/v1 bundle exec rake openapi:generate
 ```
 
+There's also a dependency-free plain-Grape example at `example/` (run
+`bundle exec ruby example/generate.rb` to produce `example/openapi.json`), which
+additionally showcases nested params and the collision-free schema naming.
+
 ---
 
 ## Type reference

data/lib/grape_openapi3/builders/operation_builder.rb

@@ -40,9 +40,8 @@ module GrapeOpenapi3
         responses[success_code] = build_success_response
 
         @route[:failure_codes].each do |info|
-          code    = (info[:code] || info["code"]).to_s
-          message = info[:message] || info["message"] || ""
-          responses[code] = { "description" => message }
+          code = (info[:code] || info["code"]).to_s
+          responses[code] = build_failure_response(info)
         end
 
         # Add 401 automatically when the API uses security and the route hasn't
@@ -83,22 +82,37 @@ module GrapeOpenapi3
 
         # Unpack hash form: { code: 201, message: "Created", model: ProductEntity, schema: {...} }
         description, entity_class, inline_schema = unpack_success(entity)
+        build_response(description, entity_class, inline_schema, is_array: @route[:is_array])
+      end
+
+      # A failure entry may carry a typed body, e.g.
+      #   failure: [{ code: 422, message: "Validation error", model: ErrorEntity }]
+      #   failure: [{ code: 404, message: "Not found", schema: { ... } }]
+      # Without :model/:schema it stays a bare { "description" => message }.
+      def build_failure_response(info)
+        message       = info[:message] || info["message"] || ""
+        model         = info[:model]   || info["model"]
+        inline_schema = info[:schema]  || info["schema"]
+        is_array      = info[:is_array] || info["is_array"] || false
+
+        build_response(message, (model if model.is_a?(Class)), inline_schema, is_array: is_array)
+      end
+
+      # Shared builder for success and failure responses.
+      def build_response(description, entity_class, inline_schema, is_array:)
+        media = @route[:produces].first || "application/json"
 
         if inline_schema
-          media = @route[:produces].first || "application/json"
           return { "description" => description, "content" => { media => { "schema" => inline_schema } } }
         end
 
-        unless entity_class
-          return { "description" => description }
-        end
+        return { "description" => description } unless entity_class
 
         schema_name = @entity_reader.register(entity_class)
         return { "description" => description } unless schema_name
 
         ref    = { "$ref" => "#/components/schemas/#{schema_name}" }
-        schema = @route[:is_array] ? { "type" => "array", "items" => ref } : ref
-        media  = @route[:produces].first || "application/json"
+        schema = is_array ? { "type" => "array", "items" => ref } : ref
 
         { "description" => description, "content" => { media => { "schema" => schema } } }
       end

data/lib/grape_openapi3/document.rb

@@ -22,7 +22,7 @@ module GrapeOpenapi3
         .compact
 
       # Pre-scan all reachable entities so schema names are stable and collision-free.
-      entity_reader.prepare(route_list.flat_map { |rd| success_entity_classes(rd) })
+      entity_reader.prepare(route_list.flat_map { |rd| referenced_entity_classes(rd) })
 
       paths      = build_paths(route_list, entity_reader)
       components = build_components(entity_reader)
@@ -42,16 +42,25 @@ module GrapeOpenapi3
 
     private
 
-    # The Grape::Entity class(es) referenced by a route's success response, if any.
-    # Handles both the bare-class form and the hash form ({ model: SomeEntity }).
-    def success_entity_classes(route_data)
-      entity = route_data[:success_entity]
-      klass  = if entity.is_a?(Class)
-                 entity
-               elsif entity.is_a?(Hash)
-                 entity[:model] || entity["model"]
-               end
-      klass.is_a?(Class) ? [klass] : []
+    # Every Grape::Entity class referenced by a route — success AND failure
+    # responses — so the pre-scan can assign collision-free names to all of them.
+    def referenced_entity_classes(route_data)
+      classes = [entity_class_of(route_data[:success_entity])]
+      Array(route_data[:failure_codes]).each do |info|
+        classes << entity_class_of(info) if info.is_a?(Hash)
+      end
+      classes.compact
+    end
+
+    # Extracts a Grape::Entity class from the bare-class form or the hash form
+    # ({ model: SomeEntity }). Returns nil when there is none.
+    def entity_class_of(entity)
+      klass = if entity.is_a?(Class)
+                entity
+              elsif entity.is_a?(Hash)
+                entity[:model] || entity["model"]
+              end
+      klass if klass.is_a?(Class)
     end
 
     def build_paths(route_list, entity_reader)

data/lib/grape_openapi3/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GrapeOpenapi3
-  VERSION = "0.1.5"
+  VERSION = "0.1.6"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: grape_openapi3
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.6
 platform: ruby
 authors:
 - rodrigonbarreto