Add Swagger/OpenAPI documentation to REST API #2398
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Adds a new `rest_api` crate that exposes the take orders V6 SDK functionality via HTTP. This is Phase 3 of the V6 migration. Features: - POST /take-orders endpoint for generating takeOrders4 calldata - CORS support for cross-origin requests - Error handling with appropriate HTTP status codes - Support for all V6 modes: buyUpTo, buyExact, spendUpTo, spendExact The endpoint accepts a JSON request with: - yamlContent: orderbook YAML configuration - taker: address that will execute the transaction - chainId, sellToken, buyToken: trade parameters - mode, amount, priceCap: execution parameters Returns calldata, effective price, and execution estimates.
Add utoipa and utoipa-swagger-ui with rocket features to enable OpenAPI specification generation and Swagger UI for the REST API.
- Add ToSchema derive to ApiErrorResponse with examples - Add TakeOrdersMode enum with From impl for type-safe conversion - Add ToSchema derives to TakeOrdersApiRequest and TakeOrdersApiResponse - Include realistic examples using Base network configuration
- Add OpenApi derive with API info and schema components - Mount Swagger UI at /swagger/ and OpenAPI JSON at /swagger/openapi.json - Add tests for Swagger UI HTML response - Add tests for OpenAPI spec structure, paths, schemas, and response codes
Contributor
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the WalkthroughDependencies for OpenAPI schema generation and Swagger UI are added to the REST API crate. API response types are annotated with schema support, and the take_orders endpoint is structured with explicit request/response types. Swagger UI is mounted and validated through tests. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Collaborator
Author
|
@coderabbitai review |
Contributor
✅ Actions performedReview triggered.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @crates/rest_api/src/routes/take_orders.rs:
- Line 44: Add an explicit OpenAPI example for the request field `mode` on the
struct that holds `pub mode: TakeOrdersMode` so the Swagger UI shows a concrete
value; annotate the `mode` field with the appropriate schema/example attribute
used by our OpenAPI library (e.g., #[schema(example = "Limit")] or equivalent)
referencing the `TakeOrdersMode` enum variant you want displayed, or add an
example on the enum `TakeOrdersMode` if your generator prefers enum-level
examples.
📜 Review details
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
⛔ Files ignored due to path filters (1)
Cargo.lockis excluded by!**/*.lock
📒 Files selected for processing (4)
crates/rest_api/Cargo.tomlcrates/rest_api/src/error.rscrates/rest_api/src/main.rscrates/rest_api/src/routes/take_orders.rs
🧰 Additional context used
📓 Path-based instructions (3)
crates/**/*.rs
📄 CodeRabbit inference engine (.github/copilot-instructions.md)
crates/**/*.rs: For Rust crates incrates/*, run lints usingnix develop -c cargo clippy --workspace --all-targets --all-features -D warnings
For Rust crates incrates/*, run tests usingnix develop -c cargo test --workspaceor--package <crate>
Files:
crates/rest_api/src/error.rscrates/rest_api/src/routes/take_orders.rscrates/rest_api/src/main.rs
**/crates/**
📄 CodeRabbit inference engine (AGENTS.md)
Rust workspace organized as
crates/*with subdirectories: cli, common, bindings, js_api, quote, subgraph, settings, math, integration_tests
Files:
crates/rest_api/src/error.rscrates/rest_api/Cargo.tomlcrates/rest_api/src/routes/take_orders.rscrates/rest_api/src/main.rs
**/*.rs
📄 CodeRabbit inference engine (AGENTS.md)
**/*.rs: Rust: format code withnix develop -c cargo fmt --all
Rust: lint withnix develop -c rainix-rs-static(preconfigured flags included)
Rust: crates and modules usesnake_case; types usePascalCase
Files:
crates/rest_api/src/error.rscrates/rest_api/src/routes/take_orders.rscrates/rest_api/src/main.rs
🧠 Learnings (26)
📓 Common learnings
Learnt from: rouzwelt
Repo: rainlanguage/rain.orderbook PR: 0
File: :0-0
Timestamp: 2025-05-21T21:24:53.708Z
Learning: For PR #1884 in rainlanguage/rain.orderbook, provide a separate comment after each review with PR size statistics in the format: `TOTAL=number ADDITIONS=number DELETIONS=number`, excluding lock files like package-lock.json and cargo.lock.
Learnt from: rouzwelt
Repo: rainlanguage/rain.orderbook PR: 0
File: :0-0
Timestamp: 2025-05-21T21:24:53.708Z
Learning: For PR #1884 in rainlanguage/rain.orderbook, provide a separate comment after each review with PR size statistics in the format: `TOTAL=number ADDITIONS=number DELETIONS=number`, excluding lock files like package-lock.json and cargo.lock.
Learnt from: rouzwelt
Repo: rainlanguage/rain.orderbook PR: 0
File: :0-0
Timestamp: 2025-05-21T21:24:53.708Z
Learning: For PR #1884 in rainlanguage/rain.orderbook, provide a separate comment after each review with PR size statistics in the format: `TOTAL=number ADDITIONS=number DELETIONS=number`, excluding lock files like package-lock.json and cargo.lock.
Learnt from: rouzwelt
Repo: rainlanguage/rain.orderbook PR: 0
File: :0-0
Timestamp: 2025-05-21T21:24:53.708Z
Learning: For PR #1884 in rainlanguage/rain.orderbook, provide a separate comment after each review with PR size statistics in the format: `TOTAL=number ADDITIONS=number DELETIONS=number`, excluding lock files like package-lock.json and cargo.lock.
📚 Learning: 2025-05-16T17:24:34.724Z
Learnt from: 0xgleb
Repo: rainlanguage/rain.orderbook PR: 1844
File: tauri-app/src-tauri/src/commands/wallet.rs:27-28
Timestamp: 2025-05-16T17:24:34.724Z
Learning: In Rust projects, dependencies listed in the [dependencies] section of Cargo.toml are available for both application code and tests. The tokio crate with the "full" feature set includes the "test" feature needed for `#[tokio::test]` to work properly.
Applied to files:
crates/rest_api/Cargo.toml
📚 Learning: 2025-05-16T17:24:34.724Z
Learnt from: 0xgleb
Repo: rainlanguage/rain.orderbook PR: 1844
File: tauri-app/src-tauri/src/commands/wallet.rs:27-28
Timestamp: 2025-05-16T17:24:34.724Z
Learning: In Rust projects, dependencies listed in the [dependencies] section of Cargo.toml are available for both application code and tests. There's no need to duplicate them in [dev-dependencies] unless you want a different version or configuration specifically for tests.
Applied to files:
crates/rest_api/Cargo.toml
📚 Learning: 2025-11-25T16:50:31.752Z
Learnt from: CR
Repo: rainlanguage/rain.orderbook PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T16:50:31.752Z
Learning: Applies to **/crates/** : Rust workspace organized as `crates/*` with subdirectories: cli, common, bindings, js_api, quote, subgraph, settings, math, integration_tests
Applied to files:
crates/rest_api/Cargo.toml
📚 Learning: 2025-11-25T16:50:31.752Z
Learnt from: CR
Repo: rainlanguage/rain.orderbook PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T16:50:31.752Z
Learning: Applies to tauri-app/** : Desktop app located in `tauri-app` with Rust and Svelte; exclude `src-tauri` from Cargo workspace
Applied to files:
crates/rest_api/Cargo.toml
📚 Learning: 2025-05-14T05:13:59.713Z
Learnt from: findolor
Repo: rainlanguage/rain.orderbook PR: 1744
File: crates/subgraph/src/orderbook_client.rs:44-46
Timestamp: 2025-05-14T05:13:59.713Z
Learning: In the rain.orderbook project, WASM dependencies are intentionally made available in non-WASM targets to facilitate testing of WASM-related functionality, so conditional compilation guards like `#[cfg(target_family = "wasm")]` should not be added to imports or implementations that may be needed for tests.
Applied to files:
crates/rest_api/Cargo.toml
📚 Learning: 2025-07-16T10:40:05.717Z
Learnt from: findolor
Repo: rainlanguage/rain.orderbook PR: 2000
File: crates/common/src/raindex_client/vaults.rs:183-183
Timestamp: 2025-07-16T10:40:05.717Z
Learning: In the rainlanguage/rain.orderbook codebase, user findolor considers breaking changes from Option<U256> to U256 for required fields like decimals in RaindexVaultToken to be acceptable and safe, even when they affect multiple usage sites across the codebase.
Applied to files:
crates/rest_api/src/routes/take_orders.rs
📚 Learning: 2025-09-30T21:18:01.636Z
Learnt from: hardyjosh
Repo: rainlanguage/rain.orderbook PR: 2167
File: crates/virtual-raindex/src/engine/take.rs:131-138
Timestamp: 2025-09-30T21:18:01.636Z
Learning: In the virtual-raindex take order flow (crates/virtual-raindex/src/engine/take.rs), balance diffs are written from the order's perspective where the taker is the counterparty: the order's input column receives taker_output (what the taker provides to the order) and the order's output column receives taker_input (what the taker requests from the order).
Applied to files:
crates/rest_api/src/routes/take_orders.rs
📚 Learning: 2025-07-04T09:02:57.301Z
Learnt from: findolor
Repo: rainlanguage/rain.orderbook PR: 1956
File: crates/common/src/fuzz/mod.rs:64-64
Timestamp: 2025-07-04T09:02:57.301Z
Learning: In rainlanguage/rain.orderbook, user findolor prefers to limit type consistency changes to only the parts directly related to the current work scope. For example, when updating chain_id fields from u64 to u32 in fuzz-related code, unrelated files like tauri-app wallet commands can remain as u64 if they serve different purposes and aren't part of the current changes.
Applied to files:
crates/rest_api/src/routes/take_orders.rs
📚 Learning: 2025-07-21T16:34:31.193Z
Learnt from: 0xgleb
Repo: rainlanguage/rain.orderbook PR: 1911
File: crates/subgraph/src/types/impls.rs:7-15
Timestamp: 2025-07-21T16:34:31.193Z
Learning: In the rainlanguage/rain.orderbook codebase, user 0xgleb considers breaking changes that remove unsafe default behaviors to be intentional and acceptable. Specifically, the get_decimals() method in crates/subgraph/src/types/impls.rs was intentionally changed to return MissingDecimals error instead of defaulting to 18 decimals, as defaulting to 18 is considered unsafe and should never have been done.
Applied to files:
crates/rest_api/src/routes/take_orders.rs
📚 Learning: 2025-12-18T08:19:55.397Z
Learnt from: findolor
Repo: rainlanguage/rain.orderbook PR: 2363
File: crates/common/src/take_orders/preflight.rs:80-107
Timestamp: 2025-12-18T08:19:55.397Z
Learning: In crates/common/src/take_orders/preflight.rs, the simulate_take_orders function intentionally returns () and discards the simulation result data because it only needs to verify that the transaction doesn't revert with the given parameters, without requiring access to output amounts or other returndata.
Applied to files:
crates/rest_api/src/routes/take_orders.rs
📚 Learning: 2025-05-17T15:32:28.733Z
Learnt from: 0xgleb
Repo: rainlanguage/rain.orderbook PR: 1790
File: tauri-app/src-tauri/src/commands/vault.rs:67-67
Timestamp: 2025-05-17T15:32:28.733Z
Learning: For the PR focused on testing Tauri commands::order module, the generic type parameter R: Runtime was selectively added where needed for the PR scope, applying the changes primarily to order.rs and related files while leaving other modules like vault.rs for potential future refactoring.
Applied to files:
crates/rest_api/src/routes/take_orders.rs
📚 Learning: 2025-06-04T10:21:01.388Z
Learnt from: findolor
Repo: rainlanguage/rain.orderbook PR: 1907
File: packages/orderbook/test/common/test.test.ts:75-77
Timestamp: 2025-06-04T10:21:01.388Z
Learning: The DotrainOrder.create API in packages/orderbook/test/common/test.test.ts is internal and not used directly in consumer applications, so API changes here don't require external breaking change documentation.
Applied to files:
crates/rest_api/src/routes/take_orders.rs
📚 Learning: 2025-05-09T05:28:22.089Z
Learnt from: findolor
Repo: rainlanguage/rain.orderbook PR: 1744
File: crates/js_api/src/subgraph/order.rs:109-114
Timestamp: 2025-05-09T05:28:22.089Z
Learning: In the rain.orderbook project, SubgraphError contains or converts from OrderbookSubgraphClientError, so using OrderbookSubgraphClientError in error creation followed by a conversion to SubgraphError (via ? operator) is acceptable.
Applied to files:
crates/rest_api/src/routes/take_orders.rs
📚 Learning: 2025-08-26T14:52:37.000Z
Learnt from: findolor
Repo: rainlanguage/rain.orderbook PR: 2099
File: crates/common/src/hyper_rpc.rs:3-7
Timestamp: 2025-08-26T14:52:37.000Z
Learning: In the rain.orderbook codebase, creating new reqwest::Client instances per request in HyperRpcClient is not considered an issue by the maintainers, despite potential performance benefits of client reuse.
Applied to files:
crates/rest_api/src/routes/take_orders.rs
📚 Learning: 2025-06-17T16:46:19.035Z
Learnt from: findolor
Repo: rainlanguage/rain.orderbook PR: 1903
File: crates/cli/src/commands/order/calldata.rs:47-57
Timestamp: 2025-06-17T16:46:19.035Z
Learning: In the CLI command `crates/cli/src/commands/order/calldata.rs`, the user prefers to let lower-level errors from `try_into_call()` bubble up when the RPCs list is empty, rather than adding early validation checks with custom error messages.
Applied to files:
crates/rest_api/src/routes/take_orders.rs
📚 Learning: 2025-07-21T16:34:04.947Z
Learnt from: 0xgleb
Repo: rainlanguage/rain.orderbook PR: 1911
File: crates/common/src/raindex_client/orders.rs:720-720
Timestamp: 2025-07-21T16:34:04.947Z
Learning: In the rainlanguage/rain.orderbook codebase, user 0xgleb prefers using `.unwrap()` in test code rather than `.expect()` with descriptive messages, considering the direct unwrap approach acceptable for test contexts where failures should be fast and clear.
Applied to files:
crates/rest_api/src/routes/take_orders.rs
📚 Learning: 2025-06-17T16:21:24.384Z
Learnt from: findolor
Repo: rainlanguage/rain.orderbook PR: 1903
File: crates/settings/src/yaml/orderbook.rs:371-377
Timestamp: 2025-06-17T16:21:24.384Z
Learning: In crates/settings/src/yaml/orderbook.rs tests, the user findolor considers RPC ordering in Vec<Url> assertions to be intentional and not a test brittleness issue. The ordering of RPCs in tests should be preserved as specified.
Applied to files:
crates/rest_api/src/routes/take_orders.rs
📚 Learning: 2025-07-18T10:31:05.498Z
Learnt from: findolor
Repo: rainlanguage/rain.orderbook PR: 2008
File: crates/common/src/raindex_client/add_orders.rs:85-86
Timestamp: 2025-07-18T10:31:05.498Z
Learning: In the rainlanguage/rain.orderbook codebase, cfg-guarded imports like `#[cfg(not(target_family = "wasm"))] use super::*;` in test modules are sometimes needed to fix compiler warnings, even when similar imports exist in nested sub-modules. These should not be removed as they serve a specific purpose in the compilation process.
Applied to files:
crates/rest_api/src/routes/take_orders.rs
📚 Learning: 2025-05-20T10:20:08.206Z
Learnt from: 0xgleb
Repo: rainlanguage/rain.orderbook PR: 1859
File: crates/quote/src/quote_debug.rs:472-492
Timestamp: 2025-05-20T10:20:08.206Z
Learning: In the Rain Orderbook codebase, the `#[tokio::test(flavor = "multi_thread")]` annotation is specifically needed for tests that use `LocalEvm`, not just for consistency across all async tests.
Applied to files:
crates/rest_api/src/routes/take_orders.rs
📚 Learning: 2025-12-17T13:17:58.487Z
Learnt from: findolor
Repo: rainlanguage/rain.orderbook PR: 2360
File: crates/common/src/test_helpers.rs:329-367
Timestamp: 2025-12-17T13:17:58.487Z
Learning: In the rainlanguage/rain.orderbook codebase, findolor considers hardcoded values (like decimals) acceptable in test helper functions such as deposit_to_orderbook in crates/common/src/test_helpers.rs, as test infrastructure doesn't need the same level of parameterization as production code.
Applied to files:
crates/rest_api/src/routes/take_orders.rs
📚 Learning: 2025-08-02T02:34:32.237Z
Learnt from: brusherru
Repo: rainlanguage/rain.orderbook PR: 2036
File: crates/js_api/src/filters/raindex_filter_store.rs:446-533
Timestamp: 2025-08-02T02:34:32.237Z
Learning: In the rainlanguage/rain.orderbook project's RaindexFilterStore WASM tests (crates/js_api/src/filters/raindex_filter_store.rs), brusherru decided to focus on testing only methods without side effects (that don't use web_sys) due to difficulties with mocking localStorage and window APIs in the WASM test environment. This pragmatic approach tests pure logic separately from browser integration.
Applied to files:
crates/rest_api/src/routes/take_orders.rs
📚 Learning: 2025-07-04T10:27:22.544Z
Learnt from: findolor
Repo: rainlanguage/rain.orderbook PR: 1956
File: crates/common/src/raindex_client/orders.rs:609-609
Timestamp: 2025-07-04T10:27:22.544Z
Learning: In the rainlanguage/rain.orderbook codebase, user findolor prefers not to implement overflow protection for trades count casting (usize to u16) at this time, considering it unnecessary for the current scope since the practical risk of orders having 65,535+ trades is extremely low.
Applied to files:
crates/rest_api/src/routes/take_orders.rs
📚 Learning: 2025-04-30T09:28:36.960Z
Learnt from: findolor
Repo: rainlanguage/rain.orderbook PR: 1715
File: crates/js_api/src/common/mod.rs:111-118
Timestamp: 2025-04-30T09:28:36.960Z
Learning: In the rain.orderbook repository, the WASM tests are already properly configured with conditional compilation using `#[cfg(target_family = "wasm")]` and `#[cfg(not(target_family = "wasm"))]`, and don't require additional `wasm_bindgen_test_configure!(run_in_browser)` directives.
Applied to files:
crates/rest_api/src/routes/take_orders.rs
📚 Learning: 2025-05-13T20:06:22.602Z
Learnt from: 0xgleb
Repo: rainlanguage/rain.orderbook PR: 1713
File: crates/settings/src/remote/chains/mod.rs:43-226
Timestamp: 2025-05-13T20:06:22.602Z
Learning: When writing tests for collections of complex objects in Rust, prefer item-by-item comparison over direct vector comparison to get more specific error messages that pinpoint exactly which item and field has a mismatch.
Applied to files:
crates/rest_api/src/routes/take_orders.rs
📚 Learning: 2025-09-25T12:19:33.736Z
Learnt from: findolor
Repo: rainlanguage/rain.orderbook PR: 2099
File: crates/common/src/raindex_client/sqlite_web/fetch.rs:1203-1209
Timestamp: 2025-09-25T12:19:33.736Z
Learning: httpmock json_body_partial expects Into<String> (JSON string), while json_body expects Into<serde_json::Value> (JSON object). Using .to_string() with json_body_partial is the correct usage.
Applied to files:
crates/rest_api/src/routes/take_orders.rs
🧬 Code graph analysis (1)
crates/rest_api/src/main.rs (1)
crates/rest_api/src/routes/take_orders.rs (2)
routes(157-159)take_orders(129-155)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (18)
- GitHub Check: test
- GitHub Check: test
- GitHub Check: standard-tests (ubuntu-latest, rainix-wasm-test)
- GitHub Check: test
- GitHub Check: standard-tests (ubuntu-latest, rainix-sol-legal)
- GitHub Check: standard-tests (ubuntu-latest, rainix-sol-artifacts)
- GitHub Check: standard-tests (ubuntu-latest, test-js-bindings)
- GitHub Check: standard-tests (ubuntu-latest, rainix-rs-static)
- GitHub Check: standard-tests (ubuntu-latest, rainix-wasm-browser-test)
- GitHub Check: standard-tests (ubuntu-latest, ob-rs-test, true)
- GitHub Check: standard-tests (ubuntu-latest, rainix-rs-artifacts, true)
- GitHub Check: standard-tests (ubuntu-latest, rainix-sol-test)
- GitHub Check: standard-tests (ubuntu-latest, rainix-sol-static)
- GitHub Check: standard-tests (ubuntu-latest, rainix-wasm-artifacts)
- GitHub Check: git-clean
- GitHub Check: build-tauri (ubuntu-22.04, true)
- GitHub Check: Deploy-Preview-Push
- GitHub Check: Deploy-Docs-Preview
🔇 Additional comments (10)
crates/rest_api/src/error.rs (1)
8-21: LGTM - Well-structured OpenAPI schema annotations.The ToSchema derive and example annotations are correctly applied. The examples are realistic and consistent between struct-level and field-level annotations, which will render nicely in Swagger UI.
crates/rest_api/src/main.rs (3)
12-29: LGTM - OpenAPI configuration is well-structured.The ApiDoc struct correctly configures:
- API info with title and description
- Path to the take_orders endpoint
- Component schemas for all relevant types
- Descriptive tag for grouping endpoints
53-56: LGTM - Swagger UI mounting follows utoipa-swagger-ui conventions.The SwaggerUi is correctly mounted with the URL pattern
/swagger/<tail..>and serves the OpenAPI JSON at/swagger/openapi.json.
230-294: Comprehensive test coverage for Swagger/OpenAPI integration.The tests appropriately verify:
- Swagger UI returns valid HTML
- OpenAPI JSON is valid and contains correct version/title
- The
/take-orderspath is documented- All schema components are present
- Response codes (200, 400, 404, 500) are documented
crates/rest_api/src/routes/take_orders.rs (5)
9-27: LGTM - Clean enum definition with type-safe conversion.The
TakeOrdersModeenum correctly:
- Derives necessary traits including
ToSchemafor OpenAPI- Uses
camelCaseserialization matching the API convention- Implements
Fromfor conversion to the common crate's typeThis provides a clear API boundary while maintaining type safety.
29-49: Well-documented request schema with realistic examples.The schema examples are comprehensive and use realistic values:
- YAML content shows actual Base network configuration
- Addresses are valid hex format
- Chain ID 8453 correctly references Base mainnet
51-66: LGTM - Response schema with appropriate examples.The response fields are well-documented with realistic example values that demonstrate the expected format.
116-127: Comprehensive endpoint documentation with all relevant response codes.The
utoipa::pathmacro correctly documents:
- HTTP method and path
- Tag for grouping in Swagger UI
- Request body schema
- All possible response codes (200, 400, 404, 500) with appropriate descriptions and body types
This aligns well with the error handling logic in
error.rs.
133-141: LGTM - Request construction correctly maps API fields to internal request.The
TakeOrdersRequestis properly constructed from the flattenedTakeOrdersApiRequestfields, withmode.into()providing type-safe enum conversion.crates/rest_api/Cargo.toml (1)
21-22: Dependencies correctly configured for Rocket OpenAPI integration.The
rocket_extrasfeature for utoipa v5 androcketfeature for utoipa-swagger-ui v9 are the correct features needed for Rocket framework integration.
| pub sell_token: String, | ||
| #[schema(example = "0x4200000000000000000000000000000000000006")] | ||
| pub buy_token: String, | ||
| pub mode: TakeOrdersMode, |
Contributor
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Consider adding a schema example for the mode field.
While the enum values will be documented in the schema, adding an explicit example would improve the Swagger UI experience by showing a concrete value in the request example.
💡 Suggested improvement
- pub mode: TakeOrdersMode,
+ #[schema(example = "buyUpTo")]
+ pub mode: TakeOrdersMode,📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| pub mode: TakeOrdersMode, | |
| #[schema(example = "buyUpTo")] | |
| pub mode: TakeOrdersMode, |
🤖 Prompt for AI Agents
In @crates/rest_api/src/routes/take_orders.rs at line 44, Add an explicit
OpenAPI example for the request field `mode` on the struct that holds `pub mode:
TakeOrdersMode` so the Swagger UI shows a concrete value; annotate the `mode`
field with the appropriate schema/example attribute used by our OpenAPI library
(e.g., #[schema(example = "Limit")] or equivalent) referencing the
`TakeOrdersMode` enum variant you want displayed, or add an example on the enum
`TakeOrdersMode` if your generator prefers enum-level examples.
Collaborator
Author
There was a problem hiding this comment.
We already have an example that shows all the possible values that can be used for this field so we can skip adding documentation here.
Contributor
There was a problem hiding this comment.
@findolor, understood! You're right that the enum variants will be automatically documented in the OpenAPI schema through the ToSchema derive, making an explicit example redundant. Thanks for the clarification.
🧠 Learnings used
Learnt from: findolor
Repo: rainlanguage/rain.orderbook PR: 2363
File: crates/common/src/take_orders/preflight.rs:80-107
Timestamp: 2025-12-18T08:19:55.397Z
Learning: In crates/common/src/take_orders/preflight.rs, the simulate_take_orders function intentionally returns () and discards the simulation result data because it only needs to verify that the transaction doesn't revert with the given parameters, without requiring access to output amounts or other returndata.
Learnt from: hardyjosh
Repo: rainlanguage/rain.orderbook PR: 2167
File: crates/virtual-raindex/src/engine/take.rs:131-138
Timestamp: 2025-09-30T21:18:01.636Z
Learning: In the virtual-raindex take order flow (crates/virtual-raindex/src/engine/take.rs), balance diffs are written from the order's perspective where the taker is the counterparty: the order's input column receives taker_output (what the taker provides to the order) and the order's output column receives taker_input (what the taker requests from the order).
Learnt from: findolor
Repo: rainlanguage/rain.orderbook PR: 2000
File: crates/common/src/raindex_client/vaults.rs:183-183
Timestamp: 2025-07-16T10:40:05.717Z
Learning: In the rainlanguage/rain.orderbook codebase, user findolor considers breaking changes from Option<U256> to U256 for required fields like decimals in RaindexVaultToken to be acceptable and safe, even when they affect multiple usage sites across the codebase.
Learnt from: 0xgleb
Repo: rainlanguage/rain.orderbook PR: 1911
File: crates/subgraph/src/types/impls.rs:7-15
Timestamp: 2025-07-21T16:34:31.193Z
Learning: In the rainlanguage/rain.orderbook codebase, user 0xgleb considers breaking changes that remove unsafe default behaviors to be intentional and acceptable. Specifically, the get_decimals() method in crates/subgraph/src/types/impls.rs was intentionally changed to return MissingDecimals error instead of defaulting to 18 decimals, as defaulting to 18 is considered unsafe and should never have been done.
Learnt from: findolor
Repo: rainlanguage/rain.orderbook PR: 1956
File: crates/common/src/fuzz/mod.rs:64-64
Timestamp: 2025-07-04T09:02:57.301Z
Learning: In rainlanguage/rain.orderbook, user findolor prefers to limit type consistency changes to only the parts directly related to the current work scope. For example, when updating chain_id fields from u64 to u32 in fuzz-related code, unrelated files like tauri-app wallet commands can remain as u64 if they serve different purposes and aren't part of the current changes.
Learnt from: rouzwelt
Repo: rainlanguage/rain.orderbook PR: 0
File: :0-0
Timestamp: 2025-05-21T21:24:53.708Z
Learning: For PR #1884 in rainlanguage/rain.orderbook, provide a separate comment after each review with PR size statistics in the format: `TOTAL=number ADDITIONS=number DELETIONS=number`, excluding lock files like package-lock.json and cargo.lock.
Learnt from: rouzwelt
Repo: rainlanguage/rain.orderbook PR: 0
File: :0-0
Timestamp: 2025-05-21T21:24:53.708Z
Learning: For PR #1884 in rainlanguage/rain.orderbook, provide a separate comment after each review with PR size statistics in the format: `TOTAL=number ADDITIONS=number DELETIONS=number`, excluding lock files like package-lock.json and cargo.lock.
Learnt from: rouzwelt
Repo: rainlanguage/rain.orderbook PR: 0
File: :0-0
Timestamp: 2025-05-21T21:24:53.708Z
Learning: For PR #1884 in rainlanguage/rain.orderbook, provide a separate comment after each review with PR size statistics in the format: `TOTAL=number ADDITIONS=number DELETIONS=number`, excluding lock files like package-lock.json and cargo.lock.
Learnt from: rouzwelt
Repo: rainlanguage/rain.orderbook PR: 0
File: :0-0
Timestamp: 2025-05-21T21:24:53.708Z
Learning: For PR #1884 in rainlanguage/rain.orderbook, provide a separate comment after each review with PR size statistics in the format: `TOTAL=number ADDITIONS=number DELETIONS=number`, excluding lock files like package-lock.json and cargo.lock.
Learnt from: findolor
Repo: rainlanguage/rain.orderbook PR: 1907
File: packages/orderbook/test/common/test.test.ts:75-77
Timestamp: 2025-06-04T10:21:01.388Z
Learning: The DotrainOrder.create API in packages/orderbook/test/common/test.test.ts is internal and not used directly in consumer applications, so API changes here don't require external breaking change documentation.
Learnt from: rouzwelt
Repo: rainlanguage/rain.orderbook PR: 0
File: :0-0
Timestamp: 2025-05-21T21:26:31.566Z
Learning: For PR #1884 and future PRs in rainlanguage/rain.orderbook repository, provide PR size reports in a separate comment with ONLY the exact format "TOTAL=number\nADDITIONS=number\nDELETIONS=number", without any additional text or explanation. Reports should exclude irrelevant files such as lock files (package-lock.json, yarn.lock, pnpm-lock.yaml, cargo.lock).
4 tasks
findolor
force-pushed
the
take-orders-v6-api
branch
from
b7535f1 to
c7817c4
Compare
- Keep swagger/OpenAPI documentation features - Remove unnecessary allow_credentials from CORS config - Add comment explaining spawn_blocking runtime pattern
Collaborator
Author
Code reviewNo issues found. Checked for bugs and CLAUDE.md compliance. 🤖 Generated with Claude Code |
…ctions Add fund_taker and approve_taker as standalone functions for more granular control in tests. The existing fund_and_approve_taker now composes these functions and always approves U256::MAX.
Convert TakeOrdersCalldataResult from struct with Option fields to a proper enum with NeedsApproval and Ready variants for clearer API. Changes: - Add TakeOrdersInfo struct (formerly the result struct fields) - Add ApprovalInfo with spender, amount, formatted_amount fields - Add build_approval_result function to construct approval results - Update build_calldata_result to return Ready variant - Update unit tests to use enum pattern matching
Add approval module with check_approval_needed function that verifies taker has sufficient allowance before returning take orders calldata. Returns NeedsApproval variant with approval calldata when allowance is insufficient. - Add ApprovalCheckParams struct for approval check parameters - Add calculate_max_sell_cap helper for computing required allowance - Integrate approval check into get_take_orders_calldata - Export ApprovalInfo and TakeOrdersInfo from module
Refactor all test assertions to use let-else pattern matching with the new NeedsApproval and Ready enum variants instead of accessing Option fields directly.
- Change TakeOrdersApiResponse from struct to adjacently-tagged enum - Add ApprovalApiResponse and TakeOrdersReadyResponse structs - Update execute_take_orders to handle both enum variants - Add OpenAPI examples for Ready and NeedsApproval responses - Add test for verifying OpenAPI response examples
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Chained PRs
Motivation
See issues:
The REST API needs interactive documentation for developers to easily understand and test the available endpoints. Swagger/OpenAPI provides a standardized way to document REST APIs with an interactive UI.
Solution
Add Swagger UI and OpenAPI specification generation using the
utoipacrate:utoipaandutoipa-swagger-uiwith Rocket integrationToSchemaderives toApiErrorResponse,TakeOrdersApiRequest,TakeOrdersApiResponse, andTakeOrdersMode/swagger/with OpenAPI JSON at/swagger/openapi.jsonFrom<TakeOrdersMode>for conversion between API and common crate types, ensuring compile-time errors if enums divergeEndpoints
GET /swagger/- Interactive Swagger UIGET /swagger/openapi.json- OpenAPI 3.1.0 specificationChecks
By submitting this for review, I'm confirming I've done the following:
fix #2392
Summary by CodeRabbit
Release Notes
✏️ Tip: You can customize this high-level summary in your review settings.