metosin / metosin/compojure-api

Generating realistic example values

Open
#403 0 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)
1.1.11

## Problem

I'm experimenting with compojure-api for documenting a new set of APIs with Prismatic Schema. It;s working well so far, though I have one issue which is not obvious how to resolve - how to generate realistic example values for an input / output schema.

Currently I get Example Values in the swagger UI like this:

```
{
"name": "string",
"description": "string",
"type": "assetClass1",
"ownerID": "string"
"dateCreated": "2018-11-19T01:25:04.282Z",
}
```

In this case, I need ownerID to be a 64 character hex string which satisfies a custom `valid-user-id?` predicate, which defined in Schema as something like:

```
(s/defschema UserID
(s/constrained s/Str valid-user-id? "Valid User ID"))
```

However it's not clear how to get compojure-api to generate valid values which satisfy the constraint (The value "string" doesn't....) and display these to the user in the Swagger UI.

Is there a way to do this? Ideally I would like to be able to specify a custom generator for the schema, which I build easily enough with `test.check` but how do I get that to be reflected in the Swagger UI?

Any help much appreciated!

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 by tracing how Prismatic Schema definitions become Swagger UI example values, then compare that path with the custom generator described using test.check. The issue is complete when a schema can provide realistic values satisfying constraints, and those values appear in the generated Swagger UI examples.

Written by the indexing model from the issue text.

Assessment

Tech stack
clojure, openapi
Domain
api, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.