metosin / metosin/compojure-api

Can't get Swagger UI to provide interface for arbitrary query params

Open
#455 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Clojure
Stars
1.1k
Forks
146
PR merge metrics
No merged PRs in 30d

Description

## Library Version(s)
2.0.0-alpha31

## Problem
Swagger can display a [UI](https://stackoverflow.com/questions/49582559/how-to-document-dynamic-query-parameter-names-in-openapi-swagger ) for setting dynamic query parameters, but I can't figure out how to do it with compojure-api.

I have a /find endpoint which needs to receive arbitrary query parameters.

E.g., Given `/api/find?x=1&y=2&z=3` I want to receive a map {:x 1, :y 2, :3} somewhere in my handler. The keys are chosen by the requester.

```clojure
(ns myns (:require [schema.core :as scm]))

(def myapp
(api ...
(GET "/find" [& fields]
:return scm/Any
(ok fields))
```
This works:
```bash
curl 'localhost:8080/api/runs/find?a=1&b=2'
{"a":"1","b":"2"}%
```
But the Swagger UI does not provide a way to set the query parameters:
![image](https://user-images.githubusercontent.com/2592723/151246569-1f27656a-71d0-4b0c-a85f-f62c0833f8d6.png)

I've tried variants of the route, providing
```clojure
:query [fields scm/Any]
```
And many other things. I can't seem to find documentation for the arguments to `:query`. (Also, does anyone understand what `:-` is for?)

If I use a schema that starts with `schema.core/maybe`...
```clojure
(scm/defschema QueryArgs (scm/maybe (scm/cond-pre scm/Num scm/Str scm/Bool scm/Keyword scm/Uuid)))
```
and provide this to :query...
```clojure
(GET "/find" [& fields]
:return scm/Any
:query [fields QueryArgs]
(ok))
```
Swagger at least shows a box that allows me to assign several values inside another parameter, but it's not the one I want:
![image](https://user-images.githubusercontent.com/2592723/151249567-7aa19917-8402-499b-8f38-e807a566b79a.png)

It produces a URL like this:
```
curl -X GET --header 'Accept: application/json' 'http://localhost:8080/api/runs/find?schemas=a%3D1&schemas=b%3D2'
```
But I want
```
curl -X GET --header 'Accept: application/json' 'http://localhost:8080/api/runs/find?a=1&b=2'
````

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the GET "/find" route and its :query declaration, then inspect how compojure-api turns arbitrary query maps into the OpenAPI/Swagger description. Done means Swagger UI can emit ?a=1&b=2 for requester-chosen keys while the existing handler receives the map; verify against the curl examples.

Written by the indexing model from the issue text.

Assessment

Tech stack
clojure, openapi
Domain
api, documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.