Add option to create references for models

[HughPowell]

When users use Swagger to automatically generate clients inline models create can create multiple classes for the logically same model.

Add and option (:refs?) to create references and a high level definitions key to hold references.

[codecov-commenter]

Codecov Report

Merging #274 (3702f2a) into master (d15ec93) will increase coverage by 0.13%. Report is 4 commits behind head on master. The diff coverage is 94.23%.

@@            Coverage Diff             @@
##           master     #274      +/-   ##
==========================================
+ Coverage   88.01%   88.15%   +0.13%     
==========================================
  Files          16       16              
  Lines        2052     2110      +58     
  Branches      183      185       +2     
==========================================
+ Hits         1806     1860      +54     
- Misses         63       65       +2     
- Partials      183      185       +2     

Files Changed	Coverage Δ
src/spec_tools/swagger/core.cljc	96.13% <94.23%> (-1.43%)	:arrow_down:

... and 1 file with indirect coverage changes

[opqdonut]

This is related to metosin/reitit#558

[HughPowell]

Sorry @opqdonut, I've been away for the last month. This has now been updated, tested and ready for review.

[opqdonut]

Thanks for the ping! I've got a lot on my plate right now but I'll try to have a look at this and remember the context. Feel free to ping me again if you don't hear back.

[HughPowell]

Hi @opqdonut, just following up on this. Thanks, Hugh.

[opqdonut]

Thanks for the ping! The code looks good in general (I'll have to do a careful reread though), but I have some doubts about how this interacts with some bugs & future developments we have on the reitit side. I'll try to get a small cabal together and think about these things.

Have you tested this change with reitit? Or are you using some other routing library?

[opqdonut]

Some notes:

• this adds :definitions for spec swagger
  • ~only inside parameters~
  • ~automatically, i.e. every parameter gets a :definition~
  • everywhere, lifted to the very top of the swagger fragment generated
    • see note https://github.com/metosin/spec-tools/pull/274#discussion_r1345199233
  • :definitions are given for swagger fragments that have a :title
• meanwhile https://github.com/metosin/malli/pull/863 added :definitions for malli swagger
  • everywhere, lifted to the very top level of the swagger fragment
  • :definitions are based on the malli registry structure

[HughPowell]

Have you tested this change with reitit? Or are you using some other routing library?

Yes, this has (only) been tested with Reitit.