How to use parameters and responses?
Nobody has claimed this yet.
Assessment
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Newbie friendliness
- 35/100
- Issue type
- Documentation
- Clarity
- Mostly clear
- Activity status
- Stale
- Tech stack
- ocaml
- Domain
- api, documentation
Research direction
Start with README.md and the OpenRouter.response and OpenRouter.parameter calls shown in hello.ml and hallo.ml. Trace the expected response_object and parameter_object types to determine how parameters and responses are declared and how path parameters are mapped. Done means adding a concise working example and explanation for both uses.
Written by the indexing model from the issue text.
Description
I'm trying to use this project to document our API, and the code from the readme.md works just fine. But I cannot figure out how to add parameters and responses.
The code below, as is, works. But when I uncomment one of the lines with the response I get errors.
Second line uncommented:
# dune exec ./hello.exe
File "hello.ml", line 36, characters 43-65:
36 | ~responses:[(OpenRouter.response "200" {description = "lala"})]
^^^^^^^^^^^^^^^^^^^^^^
Error: This expression should not be a record, the expected type is
Openapi_router__.Spec.response_object
Openapi_router__.Json_schema.or_ref
I would have expected ocaml to convert the type.
First line uncommented:
# dune exec ./hello.exe
File "hello.ml", line 35, characters 43-66:
35 | ~responses:[(OpenRouter.response "200" "{description: 'lala'}")]
^^^^^^^^^^^^^^^^^^^^^^^
Error: This expression has type string but an expression was expected of type
Openapi_router.Spec.response_object
Openapi_router__Json_schema.or_ref
I would have expected yojson to parse this, and that it works.
Actual code
In the actual code, I'm getting a somewhat different error, which suggests that yojson is actually working, but the type is for some reason wrong. It includes the -> OpenRouter.t -> OpenRouter.t part, which is in the definition, but not expected. This is also confusing.
dune exec ./hallo.exe
File "hallo.ml", line 165, characters 17-56:
165 | ~parameters:[(OpenRouter.parameter "{name: 'lala'}")]
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Error (warning 5 [ignored-partial-application]): this function application is partial,
maybe some arguments are missing.
File "hallo.ml", line 165, characters 17-56:
165 | ~parameters:[(OpenRouter.parameter "{name: 'lala'}")]
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Error: This expression has type
Openapi_router.Spec.parameter_object
Openapi_router__Json_schema.or_ref -> OpenRouter.t -> OpenRouter.t
but an expression was expected of type
Openapi_router.Spec.parameter_object
Openapi_router__Json_schema.or_ref
If you want I can try and trim down the actual code. It's currently just very bloated with types and stuff, which just distracts.
I would appreciate any example showing how parameters and responses should be declared. Also maybe a short explanation on how to map parameters from the ~parameters to the ones automatically extracted from the path.
Here is my code:
module Config = struct
type app = Dream.handler
type route = Dream.route
type handler = Dream.handler
let json_path = "/openapi.json"
let doc_path = "/docs"
let json_route json = Dream.get json_path (fun _ -> Dream.json json)
let doc_route html = Dream.get doc_path (fun _ -> Dream.html html)
let get = Dream.get
let post = Dream.post
let delete = Dream.delete
let put = Dream.put
let options = Dream.options
let head = Dream.head
let patch = Dream.patch
let build_routes = Dream.router
end
module OpenRouter = Openapi_router.Make (Config)
let circumference = fun request ->
Dream.html (
let radius = (float_of_string (Dream.param request "radius")) in
(string_of_float (Float.mul 6.28 radius)))
let start () =
OpenRouter.empty
|> OpenRouter.description "My app description"
|> OpenRouter.get ~description:"Circles and suff"
(* ~responses:[(OpenRouter.response "200" "{description: 'lala'}")] *)
(* ~responses:[(OpenRouter.response "200" {description = "lala"})] *)
"/circumference/:radius" circumference
|> OpenRouter.build
|> Dream.logger
|> Dream.run ~interface:"0.0.0.0" ~port:8080
let () = start ()
- Dominant language
- OCaml
- Stars
- 9
- Forks
- 4
- PR merge metrics
- No merged PRs in 30d
Getting set up
We have not checked this project's setup files yet. Start from its README, and see our first-contribution guide for the general steps.
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from marigold-dev/openapi-router
-
Difficulty 2/5 1-3 hours Newbie friendliness 55/100
-
Difficulty 3/5 1-2 days Newbie friendliness 48/100
-
Difficulty 3/5 1-2 days Newbie friendliness 45/100
marigold-dev/openapi-router#1 · 1 reaction ·
All issues in marigold-dev/openapi-router
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
run-llama/llama_index#23278 ·
Maintainers usually reply within 2 days
-
from-review-extraction priority: low python severity:nit
Difficulty 2/5 1-3 hours Newbie friendliness 90/100
LearningCircuit/local-deep-research#6944 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
iMicknl/python-overkiz-api#2263 ·
Maintainers usually reply within 7 days
-
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
meshery/meshery#22119 · 1 comment ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
sgl-project/sglang#41482 ·
Maintainers usually reply within 1 day