git.iko.soy/typeable/swagger2
on master help sign in
swap
5470313292 ahead, 0 behind
40 files changed+5328−1572
since splitsnapshots
unifiedsplit
.ghci+2 .gitignore+2 .travis.yml+150−67 CHANGELOG.md+186−1 LICENSE+1−1 README.md+3−1 Setup.hs+31 cabal.project+2 examples/hackage.hs+40−24 hackage-docs.sh+78 src/Data/Swagger.hs+104−13 src/Data/Swagger/Declare.hs+83−5 src/Data/Swagger/Internal.hs+403−144 src/Data/Swagger/Internal/AesonUtils.hs+346 src/Data/Swagger/Internal/ParamSchema.hs+120−23 src/Data/Swagger/Internal/Schema.hs+386−81 src/Data/Swagger/Internal/Schema/Validation.hs+511 src/Data/Swagger/Internal/TypeShape.hs+66 src/Data/Swagger/Internal/Utils.hs+9−46 src/Data/Swagger/Lens.hs+30−9 src/Data/Swagger/Operation.hs+193 src/Data/Swagger/Optics.hs+597 src/Data/Swagger/ParamSchema.hs+5−2 src/Data/Swagger/Schema.hs+24−2 src/Data/Swagger/Schema/Generator.hs+114 src/Data/Swagger/Schema/Validate.hs−168 src/Data/Swagger/Schema/Validation.hs+90 src/Data/Swagger/SchemaOptions.hs+35 stack-lts-2.yaml−5 stack.yaml+7−3 swagger2.cabal+105−40 test/Data/Swagger/CommonTestTypes.hs+679 test/Data/Swagger/ParamSchemaSpec.hs+10−84 test/Data/Swagger/Schema/GeneratorSpec.hs+168 test/Data/Swagger/Schema/ValidationSpec.hs+278 test/Data/Swagger/SchemaSpec.hs+25−513 test/Data/SwaggerSpec.hs+426−330 test/DocTest.hs−8 test/SpecCommon.hs+7−2 test/doctests.hs+12
.ghcinew file+2
@@ -0,0 +1,2 @@
1+:set -itest -isrc -optP-include -optP.stack-work/dist/x86_64-linux/Cabal-1.24.2.0/build/autogen/cabal_macros.h -optP-I -optPinclude
2+:set -hide-package base-compat-0.10.4
.gitignore+2
@@ -1,4 +1,6 @@
11dist
2+dist-newstyle
3+.ghc.environment.*
24cabal-dev
35*.o
46*.hi
.travis.yml+150−67
@@ -1,79 +1,162 @@
1−# This file has been generated -- see https://github.com/hvr/multi-ghc-travis
1+# This Travis job script has been generated by a script via
2+#
3+# haskell-ci '--branches' 'master' '--haddock-jobs=>=8.4' '--output' '.travis.yml' 'swagger2.cabal'
4+#
5+# For more information, see https://github.com/haskell-CI/haskell-ci
6+#
7+# version: 0.5.20191020
8+#
29language: c
3−sudo: false
4−
10+dist: xenial
11+git:
12+ # whether to recursively clone submodules
13+ submodules: false
14+branches:
15+ only:
16+ - master
517cache:
618 directories:
7− - $HOME/.cabsnap
819 - $HOME/.cabal/packages
9−
20+ - $HOME/.cabal/store
1021before_cache:
11− - rm -fv $HOME/.cabal/packages/hackage.haskell.org/build-reports.log
12− - rm -fv $HOME/.cabal/packages/hackage.haskell.org/00-index.tar
13−
22+ - rm -fv $CABALHOME/packages/hackage.haskell.org/build-reports.log
23+ # remove files that are regenerated by 'cabal update'
24+ - rm -fv $CABALHOME/packages/hackage.haskell.org/00-index.*
25+ - rm -fv $CABALHOME/packages/hackage.haskell.org/*.json
26+ - rm -fv $CABALHOME/packages/hackage.haskell.org/01-index.cache
27+ - rm -fv $CABALHOME/packages/hackage.haskell.org/01-index.tar
28+ - rm -fv $CABALHOME/packages/hackage.haskell.org/01-index.tar.idx
29+ - rm -rfv $CABALHOME/packages/head.hackage
1430matrix:
1531 include:
16− - env: CABALVER=1.18 GHCVER=7.8.4
17− compiler: ": #GHC 7.8.4"
18− addons: {apt: {packages: [cabal-install-1.18,ghc-7.8.4,happy-1.19.5], sources: [hvr-ghc]}}
19− - env: CABALVER=1.22 GHCVER=7.10.3
20− compiler: ": #GHC 7.10.3"
21− addons: {apt: {packages: [cabal-install-1.22,ghc-7.10.3,happy-1.19.5], sources: [hvr-ghc]}}
22−
32+ - compiler: ghc-8.8.1
33+ addons: {"apt":{"sources":["hvr-ghc"],"packages":["ghc-8.8.1","cabal-install-3.0"]}}
34+ - compiler: ghc-8.6.5
35+ addons: {"apt":{"sources":["hvr-ghc"],"packages":["ghc-8.6.5","cabal-install-3.0"]}}
36+ - compiler: ghc-8.4.4
37+ addons: {"apt":{"sources":["hvr-ghc"],"packages":["ghc-8.4.4","cabal-install-3.0"]}}
38+ - compiler: ghc-8.2.2
39+ addons: {"apt":{"sources":["hvr-ghc"],"packages":["ghc-8.2.2","cabal-install-3.0"]}}
40+ - compiler: ghc-8.0.2
41+ addons: {"apt":{"sources":["hvr-ghc"],"packages":["ghc-8.0.2","cabal-install-3.0"]}}
2342before_install:
24− - unset CC
25− - export PATH=/opt/ghc/$GHCVER/bin:/opt/cabal/$CABALVER/bin:/opt/happy/1.19.5/bin:$PATH
26−
43+ - HC=$(echo "/opt/$CC/bin/ghc" | sed 's/-/\//')
44+ - WITHCOMPILER="-w $HC"
45+ - HADDOCK=$(echo "/opt/$CC/bin/haddock" | sed 's/-/\//')
46+ - HCPKG="$HC-pkg"
47+ - unset CC
48+ - CABAL=/opt/ghc/bin/cabal
49+ - CABALHOME=$HOME/.cabal
50+ - export PATH="$CABALHOME/bin:$PATH"
51+ - TOP=$(pwd)
52+ - "HCNUMVER=$(${HC} --numeric-version|perl -ne '/^(\\d+)\\.(\\d+)\\.(\\d+)(\\.(\\d+))?$/; print(10000 * $1 + 100 * $2 + ($3 == 0 ? $5 != 1 : $3))')"
53+ - echo $HCNUMVER
54+ - CABAL="$CABAL -vnormal+nowrap+markoutput"
55+ - set -o pipefail
56+ - |
57+ echo 'function blue(s) { printf "\033[0;34m" s "\033[0m " }' >> .colorful.awk
58+ echo 'BEGIN { state = "output"; }' >> .colorful.awk
59+ echo '/^-----BEGIN CABAL OUTPUT-----$/ { state = "cabal" }' >> .colorful.awk
60+ echo '/^-----END CABAL OUTPUT-----$/ { state = "output" }' >> .colorful.awk
61+ echo '!/^(-----BEGIN CABAL OUTPUT-----|-----END CABAL OUTPUT-----)/ {' >> .colorful.awk
62+ echo ' if (state == "cabal") {' >> .colorful.awk
63+ echo ' print blue($0)' >> .colorful.awk
64+ echo ' } else {' >> .colorful.awk
65+ echo ' print $0' >> .colorful.awk
66+ echo ' }' >> .colorful.awk
67+ echo '}' >> .colorful.awk
68+ - cat .colorful.awk
69+ - |
70+ color_cabal_output () {
71+ awk -f $TOP/.colorful.awk
72+ }
73+ - echo text | color_cabal_output
2774install:
28− - cabal --version
29− - echo "$(ghc --version) [$(ghc --print-project-git-commit-id 2> /dev/null || echo '?')]"
30− - if [ -f $HOME/.cabal/packages/hackage.haskell.org/00-index.tar.gz ];
31− then
32− zcat $HOME/.cabal/packages/hackage.haskell.org/00-index.tar.gz >
33− $HOME/.cabal/packages/hackage.haskell.org/00-index.tar;
34− fi
35− - travis_retry cabal update -v
36− - sed -i 's/^jobs:/-- jobs:/' ${HOME}/.cabal/config
37− - cabal install --only-dependencies --enable-tests --enable-benchmarks --dry -v > installplan.txt
38− - sed -i -e '1,/^Resolving /d' installplan.txt; cat installplan.txt
39−
40−# check whether current requested install-plan matches cached package-db snapshot
41− - if diff -u installplan.txt $HOME/.cabsnap/installplan.txt;
42− then
43− echo "cabal build-cache HIT";
44− rm -rfv .ghc;
45− cp -a $HOME/.cabsnap/ghc $HOME/.ghc;
46− cp -a $HOME/.cabsnap/lib $HOME/.cabsnap/share $HOME/.cabsnap/bin $HOME/.cabal/;
47− else
48− echo "cabal build-cache MISS";
49− rm -rf $HOME/.cabsnap;
50− mkdir -p $HOME/.ghc $HOME/.cabal/lib $HOME/.cabal/share $HOME/.cabal/bin;
51− cabal install --only-dependencies --enable-tests --enable-benchmarks;
52− fi
53−
54−# snapshot package-db on cache miss
55− - if [ ! -d $HOME/.cabsnap ];
56− then
57− echo "snapshotting package-db to build-cache";
58− mkdir $HOME/.cabsnap;
59− cp -a $HOME/.ghc $HOME/.cabsnap/ghc;
60− cp -a $HOME/.cabal/lib $HOME/.cabal/share $HOME/.cabal/bin installplan.txt $HOME/.cabsnap/;
61− fi
62−
63−# Here starts the actual work to be performed for the package under test;
64−# any command which exits with a non-zero exit code causes the build to fail.
75+ - ${CABAL} --version
76+ - echo "$(${HC} --version) [$(${HC} --print-project-git-commit-id 2> /dev/null || echo '?')]"
77+ - TEST=--enable-tests
78+ - BENCH=--enable-benchmarks
79+ - HEADHACKAGE=false
80+ - rm -f $CABALHOME/config
81+ - |
82+ echo "verbose: normal +nowrap +markoutput" >> $CABALHOME/config
83+ echo "remote-build-reporting: anonymous" >> $CABALHOME/config
84+ echo "write-ghc-environment-files: always" >> $CABALHOME/config
85+ echo "remote-repo-cache: $CABALHOME/packages" >> $CABALHOME/config
86+ echo "logs-dir: $CABALHOME/logs" >> $CABALHOME/config
87+ echo "world-file: $CABALHOME/world" >> $CABALHOME/config
88+ echo "extra-prog-path: $CABALHOME/bin" >> $CABALHOME/config
89+ echo "symlink-bindir: $CABALHOME/bin" >> $CABALHOME/config
90+ echo "installdir: $CABALHOME/bin" >> $CABALHOME/config
91+ echo "build-summary: $CABALHOME/logs/build.log" >> $CABALHOME/config
92+ echo "store-dir: $CABALHOME/store" >> $CABALHOME/config
93+ echo "install-dirs user" >> $CABALHOME/config
94+ echo " prefix: $CABALHOME" >> $CABALHOME/config
95+ echo "repository hackage.haskell.org" >> $CABALHOME/config
96+ echo " url: http://hackage.haskell.org/" >> $CABALHOME/config
97+ echo " secure: True" >> $CABALHOME/config
98+ echo " key-threshold: 3" >> $CABALHOME/config
99+ echo " root-keys:" >> $CABALHOME/config
100+ echo " fe331502606802feac15e514d9b9ea83fee8b6ffef71335479a2e68d84adc6b0" >> $CABALHOME/config
101+ echo " 1ea9ba32c526d1cc91ab5e5bd364ec5e9e8cb67179a471872f6e26f0ae773d42" >> $CABALHOME/config
102+ echo " 2c6c3627bd6c982990239487f1abd02e08a02e6cf16edb105a8012d444d870c3" >> $CABALHOME/config
103+ echo " 0a5c7ea47cd1b15f01f5f51a33adda7e655bc0f0b0615baa8e271f4c3351e21d" >> $CABALHOME/config
104+ echo " 51f0161b906011b52c6613376b1ae937670da69322113a246a09f807c62f6921" >> $CABALHOME/config
105+ - |
106+ echo "program-default-options" >> $CABALHOME/config
107+ echo " ghc-options: $GHCJOBS +RTS -M6G -RTS" >> $CABALHOME/config
108+ - cat $CABALHOME/config
109+ - rm -fv cabal.project cabal.project.local cabal.project.freeze
110+ - travis_retry ${CABAL} v2-update -v
111+ # Generate cabal.project
112+ - rm -rf cabal.project cabal.project.local cabal.project.freeze
113+ - touch cabal.project
114+ - |
115+ echo "packages: ." >> cabal.project
116+ - |
117+ - "for pkg in $($HCPKG list --simple-output); do echo $pkg | sed 's/-[^-]*$//' | (grep -vE -- '^(swagger2)$' || true) | sed 's/^/constraints: /' | sed 's/$/ installed/' >> cabal.project.local; done"
118+ - cat cabal.project || true
119+ - cat cabal.project.local || true
120+ - if [ -f "./configure.ac" ]; then (cd "." && autoreconf -i); fi
121+ - ${CABAL} v2-freeze $WITHCOMPILER ${TEST} ${BENCH} | color_cabal_output
122+ - "cat cabal.project.freeze | sed -E 's/^(constraints: *| *)//' | sed 's/any.//'"
123+ - rm cabal.project.freeze
124+ - ${CABAL} v2-build $WITHCOMPILER ${TEST} ${BENCH} --dep -j2 all | color_cabal_output
125+ - ${CABAL} v2-build $WITHCOMPILER --disable-tests --disable-benchmarks --dep -j2 all | color_cabal_output
65126script:
66− - if [ -f configure.ac ]; then autoreconf -i; fi
67− - cabal configure --enable-tests --enable-benchmarks -v2 # -v2 provides useful information for debugging
68− - cabal build # this builds all libraries and executables (including tests/benchmarks)
69− - cabal test
70− - cabal check
71− - cabal sdist # tests that a source-distribution can be generated
72−
73−# Check that the resulting source distribution can be built & installed.
74−# If there are no other `.tar.gz` files in `dist`, this can be even simpler:
75−# `cabal install --force-reinstalls dist/*-*.tar.gz`
76− - SRC_TGZ=$(cabal info . | awk '{print $2;exit}').tar.gz &&
77− (cd dist && cabal install --force-reinstalls "$SRC_TGZ")
127+ - DISTDIR=$(mktemp -d /tmp/dist-test.XXXX)
128+ # Packaging...
129+ - ${CABAL} v2-sdist all | color_cabal_output
130+ # Unpacking...
131+ - mv dist-newstyle/sdist/*.tar.gz ${DISTDIR}/
132+ - cd ${DISTDIR} || false
133+ - find . -maxdepth 1 -type f -name '*.tar.gz' -exec tar -xvf '{}' \;
134+ - find . -maxdepth 1 -type f -name '*.tar.gz' -exec rm '{}' \;
135+ - PKGDIR_swagger2="$(find . -maxdepth 1 -type d -regex '.*/swagger2-[0-9.]*')"
136+ # Generate cabal.project
137+ - rm -rf cabal.project cabal.project.local cabal.project.freeze
138+ - touch cabal.project
139+ - |
140+ echo "packages: ${PKGDIR_swagger2}" >> cabal.project
141+ - |
142+ - "for pkg in $($HCPKG list --simple-output); do echo $pkg | sed 's/-[^-]*$//' | (grep -vE -- '^(swagger2)$' || true) | sed 's/^/constraints: /' | sed 's/$/ installed/' >> cabal.project.local; done"
143+ - cat cabal.project || true
144+ - cat cabal.project.local || true
145+ # Building...
146+ # this builds all libraries and executables (without tests/benchmarks)
147+ - ${CABAL} v2-build $WITHCOMPILER --disable-tests --disable-benchmarks all | color_cabal_output
148+ # Building with tests and benchmarks...
149+ # build & run tests, build benchmarks
150+ - ${CABAL} v2-build $WITHCOMPILER ${TEST} ${BENCH} all | color_cabal_output
151+ # Testing...
152+ - ${CABAL} v2-test $WITHCOMPILER ${TEST} ${BENCH} all | color_cabal_output
153+ # cabal check...
154+ - (cd ${PKGDIR_swagger2} && ${CABAL} -vnormal check)
155+ # haddock...
156+ - if [ $HCNUMVER -ge 80400 ] ; then ${CABAL} v2-haddock $WITHCOMPILER --with-haddock $HADDOCK ${TEST} ${BENCH} all | color_cabal_output ; fi
157+ # Building without installed constraints for packages in global-db...
158+ - rm -f cabal.project.local
159+ - ${CABAL} v2-build $WITHCOMPILER --disable-tests --disable-benchmarks all | color_cabal_output
78160
161+# REGENDATA ("0.5.20191020",["--branches","master","--haddock-jobs=>=8.4","--output",".travis.yml","swagger2.cabal"])
79162# EOF
CHANGELOG.md+186−1
@@ -1,7 +1,192 @@
1+2.5
2+---
3+
4+Highlights:
5+- Add instance for `TimeOfDay` (see [#196]( https://github.com/GetShopTV/swagger2/pull/196 ));
6+- Add support for [`optics`](https://hackage.haskell.org/package/optics) (see [#200]( https://github.com/GetShopTV/swagger2/pull/200 ));
7+- Slightly better validation errors (see [#195]( https://github.com/GetShopTV/swagger2/pull/195 ));
8+
9+Fixes and minor changes:
10+- Minor cleanup (see [#194]( https://github.com/GetShopTV/swagger2/pull/194 ));
11+- Allow base-4.13 and other GHC-8.8 related stuff (see [#198]( https://github.com/GetShopTV/swagger2/pull/198 ));
12+- Fix `stack.yaml` (see [#201]( https://github.com/GetShopTV/swagger2/pull/201 ));
13+
14+2.4
15+---
16+
17+- Allow hashable-1.3, semigroups-0.19, network-3.1, time-1.9, generics-sop-0.5
18+- Tags aren't sorted
19+ (see [#165](https://github.com/GetShopTV/swagger2/issues/165))
20+- Schema type is optional
21+ (see [#138](https://github.com/GetShopTV/swagger2/issues/138), [#164](https://github.com/GetShopTV/swagger2/pull/164))
22+- Take concrete 'Proxy' as argument
23+ (see [#180](https://github.com/GetShopTV/swagger2/pull/180))
24+- GHC-8.8 preparations
25+
26+2.3.1.1
27+-------
28+
29+- Allow `network-3.0`
30+
31+2.3.1
32+-----
33+
34+- Add a quickcheck generator for aeson Values that match a swagger schema
35+ (see [#162](https://github.com/GetShopTV/swagger2/pull/162))
36+- Add `ToParamSchema` instance for `SetCookie`
37+ (see [#173](https://github.com/GetShopTV/swagger2/pull/173))
38+- Make nullary schemas valid
39+ (see [#168](https://github.com/GetShopTV/swagger2/pull/168))
40+
41+2.3.0.1
42+-------
43+
44+- Support GHC-8.6
45+
46+2.3
47+---
48+
49+Major changes:
50+
51+- Add support for `additionalProperties` with `Bool` value (see [#159](https://github.com/GetShopTV/swagger2/pull/159));
52+- Add `ToSchema` `Object` instance (for aeson's `Object`) (see [`d72466a`](https://github.com/GetShopTV/swagger2/commit/d72466a));
53+
54+Dependencies and CI:
55+
56+- Aeson 1.4 (see [#158](https://github.com/GetShopTV/swagger2/pull/158));
57+- Update .travis.yml (see [#160](https://github.com/GetShopTV/swagger2/pull/160));
58+- Allow network 2.7 (see [#155](https://github.com/GetShopTV/swagger2/pull/155));
59+- Allow lens-4.17 (see [#161](https://github.com/GetShopTV/swagger2/pull/161));
60+
61+2.2.2
62+-----
63+
64+* Add `ToSchema Version` instance
65+* Use base-compat-batteries (0.10)
66+* PVP bounds
67+
68+2.2.1
69+-----
70+
71+* Add `Semigroup` instances
72+* GHC-8.4 compatibility
73+* `Schema (NonEmpty a) instance (see [#141](https://github.com/GetShopTV/swagger2/pull/141))
74+* Fix optional property for unary records (see [#142](https://github.com/GetShopTV/swagger2/issues/142))
75+* Add `fromAesonOptions` helper (see [#146](https://github.com/GetShopTV/swagger2/issues/139))
76+* Fix non-termination when using `datatypeNameModifier` with recursive data types (see [#132](https://github.com/GetShopTV/swagger2/issues/132))
77+
78+2.2
79+---
80+
81+* Treat unknown properties as validation errors in `validateToJSON` (see [#126](https://github.com/GetShopTV/swagger2/pull/126));
82+* Add `validateJSON` and `validateJSONWithPatternChecker` to validate JSON `Value` against `Schema` without classes (see [#126](https://github.com/GetShopTV/swagger2/pull/126));
83+* Add more `Schema` helpers (see [#126](https://github.com/GetShopTV/swagger2/pull/126)):
84+ * `genericNameSchema` — to give a custom schema `Generic`-based name;
85+ * `genericDeclareNamedSchemaNewtype` — to derive `NamedSchema` for `newtype`s;
86+ * `declareSchemaBoundedEnumKeyMapping` — to derive more specific `Schema` for maps with `Bounded` `Enum` keys;
87+* Add a few tests with invalid `Schema`.
88+
89+2.1.6
90+-----
91+
92+* Add `ToParamSchema` and `ToSchema` instances for `Fixed` (see [#121](https://github.com/GetShopTV/swagger2/pull/121)) and `Natural` (see [#123](https://github.com/GetShopTV/swagger2/pull/123));
93+* Fix instance for `NominalDiffTime` (see [#121](https://github.com/GetShopTV/swagger2/pull/121));
94+* Fix build for `aeson-1.2.2.0` (see [#125](https://github.com/GetShopTV/swagger2/pull/125)).
95+
96+2.1.5
97+-----
98+
99+* Type error by default when deriving Generic-based instances for mixed sum types (see [#118](https://github.com/GetShopTV/swagger2/pull/118));
100+* Adjust `allOf` to accept referenced schemas (see [#119](https://github.com/GetShopTV/swagger2/issues/119));
101+* Add instances for `Identity` (see [#116](https://github.com/GetShopTV/swagger2/pull/116));
102+* Add Gitter chat badge (see [#114](https://github.com/GetShopTV/swagger2/pull/114)).
103+
104+2.1.4.1
105+-------
106+
107+* GHC-8.2 support (see [#95](https://github.com/GetShopTV/swagger2/issues/95), [#106](https://github.com/GetShopTV/swagger2/pull/106) and [#108](https://github.com/GetShopTV/swagger2/pull/108));
108+* Documentation corrections (see [#105](https://github.com/GetShopTV/swagger2/pull/105));
109+* Allow `generics-sop-0.3` (see [#102](https://github.com/GetShopTV/swagger2/pull/102));
110+* Fix `ToSchema` example in docs (see [#104](https://github.com/GetShopTV/swagger2/pull/104)).
111+
112+2.1.4
113+-----
114+
115+* Add `liftDeclare` (see [#100](https://github.com/GetShopTV/swagger2/pull/100));
116+* Add `MonadDeclare` instances for all monad transformers (see [#100](https://github.com/GetShopTV/swagger2/pull/100)).
117+
118+2.1.3
119+-----
120+
121+* Add [`UUID`](http://hackage.haskell.org/package/uuid-types/docs/Data-UUID-Types.html#t:UUID) instances (see [#81](https://github.com/GetShopTV/swagger2/pull/81)).
122+* Add [`TypeError`](https://hackage.haskell.org/package/base-4.9.0.0/docs/GHC-TypeLits.html#g:4) `ToSchema` and `ToParamSchema ByteString` instances (see [#78](https://github.com/GetShopTV/swagger2/pull/78))
123+* Improve documentation for generic sum type instance derivation (see [#75](https://github.com/GetShopTV/swagger2/pull/75))
124+* Compile warning free (see [#82](https://github.com/GetShopTV/swagger2/pull/82))
125+
126+2.1.2.1
127+-------
128+
129+* Bug fix previous release
130+
131+2.1.2
132+---
133+
134+* Minor changes:
135+ * Support `aeson-1.0.0.0` (see [#70](https://github.com/GetShopTV/swagger2/pull/70)).
136+
137+2.1.1
138+---
139+
140+* Minor changes:
141+ * Proper `Schema` examples for `Char`, `Day`, `LocalTime`, `ZonedTime` and `UTCTime`.
142+
143+2.1
144+---
145+
146+* Major changes:
147+ * Use `InsOrdHashMap` to preserve insertion order for endpoints and definitions (see [#56](https://github.com/GetShopTV/swagger2/pull/56));
148+ * Add support for GHC 8.0 (see [#65](https://github.com/GetShopTV/swagger2/pull/65)).
149+
150+2.0.2
151+---
152+
153+* Fixes:
154+ * Fix `additionalProperties` to allow references;
155+ * Fix `ToSchema` instances for `Map` and `HashMap` (prevent infinite recursion for recursive values).
156+
157+2.0.1
158+---
159+
160+* Fixes:
161+ * Re-export `Pattern` synonym from `Data.Swagger`;
162+ * Documentation fixes.
163+
164+2.0
165+---
166+
167+* Major changes:
168+ * GHC 7.8 support (see [#49](https://github.com/GetShopTV/swagger2/pull/49));
169+ * Switch to classy field lenses (see [#41](https://github.com/GetShopTV/swagger2/pull/41));
170+ * Add `Data.Swagger.Schema.Validation` (see [#18](https://github.com/GetShopTV/swagger2/pull/18));
171+ * Add `Data.Swagger.Operation` with helpers (see [#50](https://github.com/GetShopTV/swagger2/pull/50));
172+ * Add `IsString` instances for some types (see [#47](https://github.com/GetShopTV/swagger2/pull/47));
173+ * Add helpers to sketch `Schema` from JSON (see [#48](https://github.com/GetShopTV/swagger2/pull/48)).
174+
175+* Minor changes:
176+ * Make `NamedSchema` a `data` rather than `type` (see [#42](https://github.com/GetShopTV/swagger2/pull/42));
177+ * Change `Definitions` to `Definitions Schema`;
178+ * Add schema templates for `"binary"`, `"byte"` and `"password"` formats (see [63ed597](https://github.com/GetShopTV/swagger2/commit/63ed59736dc4f942f0e2a7d668d7cee513fa9eaf));
179+ * Add `Monoid` instance for `Contact`;
180+ * Change `tags` to be `Set` rather than list.
181+
182+* Fixes:
183+ * Fix schema for `()` and nullary constructors (see [ab65c4a](https://github.com/GetShopTV/swagger2/commit/ab65c4a48253c34f8a88221a53dc97bf5e6e8d29));
184+ * Fix `Operation` `FromJSON` instance to allow missing `tags` and `parameters` properties.
185+
11861.2.1
2187---
3188
4−* Minor change:
189+* Minor changes:
5190 * Change `_SwaggerItemsPrimitive` type from a `Prism'` to a more restrictive `Review`-like `Optic'`.
6191
7192* Fixes:
LICENSE+1−1
@@ -1,4 +1,4 @@
1−Copyright (c) 2015, GetShopTV
1+Copyright (c) 2015-2017, GetShopTV
22All rights reserved.
33
44Redistribution and use in source and binary forms, with or without
README.md+3−1
@@ -1,5 +1,7 @@
11# swagger2
22
3+[![Join the chat at https://gitter.im/haskell-swagger2/Lobby](https://badges.gitter.im/haskell-swagger2/Lobby.svg)](https://gitter.im/haskell-swagger2/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
4+
35[![Hackage](https://img.shields.io/hackage/v/swagger2.svg)](http://hackage.haskell.org/package/swagger2)
46[![Build Status](https://travis-ci.org/GetShopTV/swagger2.svg?branch=master)](https://travis-ci.org/GetShopTV/swagger2)
57[![Stackage LTS](http://stackage.org/package/swagger2/badge/lts)](http://stackage.org/lts/package/swagger2)
@@ -11,7 +13,7 @@ The original Swagger 2.0 specification is available at http://swagger.io/specifi
1113
1214## Usage
1315
14−This library is inteded to be used for decoding and encoding Swagger 2.0 API specifications as well as manipulating them.
16+This library is intended to be used for decoding and encoding Swagger 2.0 API specifications as well as manipulating them.
1517
1618Please refer to [haddock documentation](http://hackage.haskell.org/package/swagger2).
1719
Setup.hs+31
@@ -1,2 +1,33 @@
1+{-# LANGUAGE CPP #-}
2+{-# OPTIONS_GHC -Wall #-}
3+module Main (main) where
4+
5+#ifndef MIN_VERSION_cabal_doctest
6+#define MIN_VERSION_cabal_doctest(x,y,z) 0
7+#endif
8+
9+#if MIN_VERSION_cabal_doctest(1,0,0)
10+
11+import Distribution.Extra.Doctest ( defaultMainWithDoctests )
12+main :: IO ()
13+main = defaultMainWithDoctests "doctests"
14+
15+#else
16+
17+#ifdef MIN_VERSION_Cabal
18+-- If the macro is defined, we have new cabal-install,
19+-- but for some reason we don't have cabal-doctest in package-db
20+--
21+-- Probably we are running cabal sdist, when otherwise using new-build
22+-- workflow
23+#warning You are configuring this package without cabal-doctest installed. \
24+ The doctests test-suite will not work as a result. \
25+ To fix this, install cabal-doctest before configuring.
26+#endif
27+
128import Distribution.Simple
29+
30+main :: IO ()
231main = defaultMain
32+
33+#endif
cabal.projectnew file+2
@@ -0,0 +1,2 @@
1+packages: .
2+tests: true
examples/hackage.hs+40−24
@@ -13,13 +13,28 @@ import GHC.Generics
1313import Data.Swagger
1414import Data.Swagger.Declare
1515import Data.Swagger.Lens
16+import Data.Swagger.Operation
1617
1718type Username = Text
1819
1920data UserSummary = UserSummary
2021 { summaryUsername :: Username
2122 , summaryUserid :: Int
22− } deriving (Generic, ToSchema)
23+ } deriving (Generic)
24+
25+instance ToSchema UserSummary where
26+ declareNamedSchema _ = do
27+ usernameSchema <- declareSchemaRef (Proxy :: Proxy Username)
28+ useridSchema <- declareSchemaRef (Proxy :: Proxy Int)
29+ return $ NamedSchema (Just "UserSummary") $ mempty
30+ & type_ ?~ SwaggerObject
31+ & properties .~
32+ [ ("summaryUsername", usernameSchema )
33+ , ("summaryUserid" , useridSchema )
34+ ]
35+ & required .~ [ "summaryUsername"
36+ , "summaryUserid" ]
37+
2338
2439type Group = Text
2540
@@ -37,32 +52,33 @@ hackageSwagger = spec & definitions .~ defs
3752 where
3853 (defs, spec) = runDeclare declareHackageSwagger mempty
3954
40−declareHackageSwagger :: Declare Definitions Swagger
55+declareHackageSwagger :: Declare (Definitions Schema) Swagger
4156declareHackageSwagger = do
57+ -- param schemas
4258 let usernameParamSchema = toParamSchema (Proxy :: Proxy Username)
43− userSummarySchemaRef <- declareSchemaRef (Proxy :: Proxy UserSummary)
44− userDetailedSchemaRef <- declareSchemaRef (Proxy :: Proxy UserDetailed)
45− packagesSchemaRef <- declareSchemaRef (Proxy :: Proxy [Package])
59+
60+ -- responses
61+ userSummaryResponse <- declareResponse (Proxy :: Proxy UserSummary)
62+ userDetailedResponse <- declareResponse (Proxy :: Proxy UserDetailed)
63+ packagesResponse <- declareResponse (Proxy :: Proxy [Package])
64+
4665 return $ mempty
47− & paths.pathsMap .~
48− [ ("/users", mempty & pathItemGet ?~ (mempty
49− & operationProduces ?~ MimeList ["application/json"]
50− & operationResponses .~ (mempty
51− & responsesResponses . at 200 ?~ Inline (mempty & responseSchema ?~ userSummarySchemaRef))))
52− , ("/user/{username}", mempty & pathItemGet ?~ (mempty
53− & operationProduces ?~ MimeList ["application/json"]
54− & operationParameters .~ [ Inline $ mempty
55− & paramName .~ "username"
56− & paramRequired ?~ True
57− & paramSchema .~ ParamOther (mempty
58− & paramOtherSchemaIn .~ ParamPath
59− & paramOtherSchemaParamSchema .~ usernameParamSchema) ]
60− & operationResponses .~ (mempty
61− & responsesResponses . at 200 ?~ Inline (mempty & responseSchema ?~ userDetailedSchemaRef))))
62− , ("/packages", mempty & pathItemGet ?~ (mempty
63− & operationProduces ?~ MimeList ["application/json"]
64− & operationResponses .~ (mempty
65− & responsesResponses . at 200 ?~ Inline (mempty & responseSchema ?~ packagesSchemaRef))))
66+ & paths .~
67+ [ ("/users", mempty & get ?~ (mempty
68+ & produces ?~ MimeList ["application/json"]
69+ & at 200 ?~ Inline userSummaryResponse))
70+ , ("/user/{username}", mempty & get ?~ (mempty
71+ & produces ?~ MimeList ["application/json"]
72+ & parameters .~ [ Inline $ mempty
73+ & name .~ "username"
74+ & required ?~ True
75+ & schema .~ ParamOther (mempty
76+ & in_ .~ ParamPath
77+ & paramSchema .~ usernameParamSchema) ]
78+ & at 200 ?~ Inline userDetailedResponse))
79+ , ("/packages", mempty & get ?~ (mempty
80+ & produces ?~ MimeList ["application/json"]
81+ & at 200 ?~ Inline packagesResponse))
6682 ]
6783
6884main :: IO ()
hackage-docs.shnew file+78
@@ -0,0 +1,78 @@
1+#!/bin/bash
2+set -e
3+
4+# This if stack-enabled fork of https://github.com/ekmett/lens/blob/master/scripts/hackage-docs.sh
5+
6+if [ "$#" -ne 1 ]; then
7+ echo "Usage: scripts/hackage-docs.sh HACKAGE_USER"
8+ exit 1
9+fi
10+
11+user=$1
12+
13+cabal_file=$(find . -maxdepth 1 -name "*.cabal" -print -quit)
14+if [ ! -f "$cabal_file" ]; then
15+ echo "Run this script in the top-level package directory"
16+ exit 1
17+fi
18+
19+pkg=$(awk -F ":[[:space:]]*" 'tolower($1)=="name" { print $2 }' < "$cabal_file")
20+ver=$(awk -F ":[[:space:]]*" 'tolower($1)=="version" { print $2 }' < "$cabal_file")
21+
22+if [ -z "$pkg" ]; then
23+ echo "Unable to determine package name"
24+ exit 1
25+fi
26+
27+if [ -z "$ver" ]; then
28+ echo "Unable to determine package version"
29+ exit 1
30+fi
31+
32+echo "Detected package: $pkg-$ver"
33+
34+dir=$(mktemp -d build-docs.XXXXXX)
35+trap 'rm -r "$dir"' EXIT
36+
37+export PATH=$(stack path --bin-path)
38+
39+ghc --version
40+cabal --version
41+stack --version
42+
43+if haddock --hyperlinked-source >/dev/null
44+then
45+ echo "Using fancy hyperlinked source"
46+ HYPERLINK_FLAG="--haddock-option=--hyperlinked-source"
47+else
48+ echo "Using boring hyperlinked source"
49+ HYPERLINK_FLAG="--hyperlink-source"
50+fi
51+
52+# Cabal dist in temporary location
53+builddir=$dir/dist
54+
55+# Build dependencies haddocks with stack, so we get links
56+stack haddock --only-dependencies
57+
58+# Configure using stack databases
59+snapshotpkgdb=$(stack path --snapshot-pkg-db)
60+localpkgdb=$(stack path --local-pkg-db)
61+cabal configure -v2 --builddir=$builddir --package-db=clear --package-db=global --package-db=$snapshotpkgdb --package-db=$localpkgdb
62+
63+# Build Hadckage compatible docs
64+cabal haddock -v2 --builddir=$builddir $HYPERLINK_FLAG --html-location='/package/$pkg-$version/docs' --contents-location='/package/$pkg-$version'
65+
66+# Copy into right directory
67+cp -R $builddir/doc/html/$pkg/ $dir/$pkg-$ver-docs
68+
69+# Tar and gzip
70+tar cvz -C $dir --format=ustar -f $dir/$pkg-$ver-docs.tar.gz $pkg-$ver-docs
71+
72+# Upload
73+curl -X PUT \
74+ -H 'Content-Type: application/x-tar' \
75+ -H 'Content-Encoding: gzip' \
76+ -u "$user" \
77+ --data-binary "@$dir/$pkg-$ver-docs.tar.gz" \
78+ "https://hackage.haskell.org/package/$pkg-$ver/docs"
src/Data/Swagger.hs+104−13
@@ -1,4 +1,9 @@
1+{-# LANGUAGE CPP #-}
12-- |
3+-- Module: Data.Swagger
4+-- Maintainer: Nickolay Kudasov <nickolay@getshoptv.com>
5+-- Stability: experimental
6+--
27-- Swagger™ is a project used to describe and document RESTful APIs.
38--
49-- The Swagger specification defines a set of files required to describe such an API.
@@ -18,10 +23,19 @@ module Data.Swagger (
1823 -- ** Schema specification
1924 -- $schema
2025
26+ -- ** Manipulation
27+ -- $manipulation
28+
29+ -- ** Validation
30+ -- $validation
31+
2132 -- * Re-exports
2233 module Data.Swagger.Lens,
34+ module Data.Swagger.Optics,
35+ module Data.Swagger.Operation,
2336 module Data.Swagger.ParamSchema,
2437 module Data.Swagger.Schema,
38+ module Data.Swagger.Schema.Validation,
2539
2640 -- * Swagger specification
2741 Swagger(..),
@@ -63,6 +77,8 @@ module Data.Swagger (
6377 NamedSchema(..),
6478 SwaggerItems(..),
6579 Xml(..),
80+ Pattern,
81+ AdditionalProperties(..),
6682
6783 -- ** Responses
6884 Responses(..),
@@ -73,6 +89,7 @@ module Data.Swagger (
7389 SecurityScheme(..),
7490 SecuritySchemeType(..),
7591 SecurityRequirement(..),
92+ SecurityDefinitions(..),
7693
7794 -- *** API key
7895 ApiKeyParams(..),
@@ -97,8 +114,11 @@ module Data.Swagger (
97114) where
98115
99116import Data.Swagger.Lens
117+import Data.Swagger.Optics ()
118+import Data.Swagger.Operation
100119import Data.Swagger.ParamSchema
101120import Data.Swagger.Schema
121+import Data.Swagger.Schema.Validation
102122
103123import Data.Swagger.Internal
104124
@@ -158,43 +178,47 @@ import Data.Swagger.Internal
158178
159179-- $lens
160180--
181+-- Note: if you're working with the <https://hackage.haskell.org/package/optics optics> library, take a look at "Data.Swagger.Optics".
182+--
161183-- Since @'Swagger'@ has a fairly complex structure, lenses and prisms are used
162−-- to work comfortly with it. In combination with @'Monoid'@ instances, lenses
184+-- to work comfortably with it. In combination with @'Monoid'@ instances, lenses
163185-- make it fairly simple to construct/modify any part of the specification:
164186--
165187-- >>> :{
166188-- encode $ (mempty :: Swagger)
167−-- & definitions .~ [ ("User", mempty & type_ .~ SwaggerString) ]
189+-- & definitions .~ [ ("User", mempty & type_ ?~ SwaggerString) ]
168190-- & paths .~
169191-- [ ("/user", mempty & get ?~ (mempty
170192-- & produces ?~ MimeList ["application/json"]
171−-- & at 200 ?~ Inline (mempty & schema ?~ Ref (Reference "User")))) ]
193+-- & at 200 ?~ ("OK" & _Inline.schema ?~ Ref (Reference "User"))
194+-- & at 404 ?~ "User info not found")) ]
172195-- :}
173−-- "{\"swagger\":\"2.0\",\"info\":{\"version\":\"\",\"title\":\"\"},\"definitions\":{\"User\":{\"type\":\"string\"}},\"paths\":{\"/user\":{\"get\":{\"responses\":{\"200\":{\"schema\":{\"$ref\":\"#/definitions/User\"},\"description\":\"\"}},\"produces\":[\"application/json\"]}}}}"
196+-- "{\"swagger\":\"2.0\",\"info\":{\"version\":\"\",\"title\":\"\"},\"paths\":{\"/user\":{\"get\":{\"produces\":[\"application/json\"],\"responses\":{\"404\":{\"description\":\"User info not found\"},\"200\":{\"schema\":{\"$ref\":\"#/definitions/User\"},\"description\":\"OK\"}}}}},\"definitions\":{\"User\":{\"type\":\"string\"}}}"
174197--
175−-- In the snippet above we declare API with a single path @/user@ providing method @GET@
176−-- which produces @application/json@ output and should respond with code @200@ and body specified
198+-- In the snippet above we declare an API with a single path @/user@. This path provides method @GET@
199+-- which produces @application/json@ output. It should respond with code @200@ and body specified
177200-- by schema @User@ which is defined in @'definitions'@ property of swagger specification.
201+-- Alternatively it may respond with code @404@ meaning that user info is not found.
178202--
179203-- For convenience, @swagger2@ uses /classy field lenses/. It means that
180204-- field accessor names can be overloaded for different types. One such
181−-- common field is @'description'@. Many components of Swagger specification
205+-- common field is @'description'@. Many components of a Swagger specification
182206-- can have descriptions, and you can use the same name for them:
183207--
184208-- >>> encode $ (mempty :: Response) & description .~ "No content"
185209-- "{\"description\":\"No content\"}"
186210-- >>> :{
187211-- encode $ (mempty :: Schema)
188−-- & type_ .~ SwaggerBoolean
212+-- & type_ ?~ SwaggerBoolean
189213-- & description ?~ "To be or not to be"
190214-- :}
191−-- "{\"type\":\"boolean\",\"description\":\"To be or not to be\"}"
215+-- "{\"description\":\"To be or not to be\",\"type\":\"boolean\"}"
192216--
193217-- @'ParamSchema'@ is basically the /base schema specification/ and many types contain it (see @'HasParamSchema'@).
194218-- So for convenience, all @'ParamSchema'@ fields are transitively made fields of the type that has it.
195219-- For example, you can use @'type_'@ to access @'SwaggerType'@ of @'Header'@ schema without having to use @'paramSchema'@:
196220--
197−-- >>> encode $ (mempty :: Header) & type_ .~ SwaggerNumber
221+-- >>> encode $ (mempty :: Header) & type_ ?~ SwaggerNumber
198222-- "{\"type\":\"number\"}"
199223--
200224-- Additionally, to simplify working with @'Response'@, both @'Operation'@ and @'Responses'@
@@ -202,7 +226,7 @@ import Data.Swagger.Internal
202226--
203227-- >>> :{
204228-- encode $ (mempty :: Operation)
205−-- & at 404 ?~ Inline (mempty & description .~ "Not found")
229+-- & at 404 ?~ "Not found"
206230-- :}
207231-- "{\"responses\":{\"404\":{\"description\":\"Not found\"}}}"
208232--
@@ -212,7 +236,7 @@ import Data.Swagger.Internal
212236-- A few other field accessors are modified in this way:
213237--
214238-- - @'in_'@, @'type_'@, @'default_'@ (as keywords);
215−-- - @'maximum_'@ and @'minimum_'@ (as conflicting with @Prelude@);
239+-- - @'maximum_'@, @'minimum_'@, @'head_'@ (as conflicting with @Prelude@);
216240-- - @'enum_'@ (as conflicting with @Control.Lens@).
217241
218242-- $schema
@@ -254,6 +278,73 @@ import Data.Swagger.Internal
254278-- >>> encode (Person "David" 28)
255279-- "{\"age\":28,\"name\":\"David\"}"
256280-- >>> encode $ toSchema (Proxy :: Proxy Person)
257−-- "{\"required\":[\"name\",\"age\"],\"type\":\"object\",\"properties\":{\"age\":{\"type\":\"integer\"},\"name\":{\"type\":\"string\"}}}"
281+-- "{\"required\":[\"name\",\"age\"],\"properties\":{\"name\":{\"type\":\"string\"},\"age\":{\"type\":\"integer\"}},\"type\":\"object\"}"
282+--
283+-- Please note that not all valid Haskell data types will have a proper swagger schema. For example while we can derive a
284+-- schema for basic enums like
285+--
286+-- >>> data SampleEnum = ChoiceOne | ChoiceTwo deriving Generic
287+-- >>> instance ToSchema SampleEnum
288+-- >>> instance ToJSON SampleEnum
289+--
290+-- and for sum types that have constructors with values
291+--
292+-- >>> data SampleSumType = ChoiceInt Int | ChoiceString String deriving Generic
293+-- >>> instance ToSchema SampleSumType
294+-- >>> instance ToJSON SampleSumType
295+--
296+-- we can not derive a valid schema for a mix of the above. The following will result in a type error
297+--
298+#if __GLASGOW_HASKELL__ < 800
299+-- >>> data BadMixedType = ChoiceBool Bool | JustTag deriving Generic
300+-- >>> instance ToSchema BadMixedType
301+-- ...
302+-- ... error:
303+-- ... • No instance for (Data.Swagger.Internal.TypeShape.CannotDeriveSchemaForMixedSumType
304+-- ... BadMixedType)
305+-- ... arising from a use of ‘Data.Swagger.Internal.Schema.$dmdeclareNamedSchema’
306+-- ... • In the expression:
307+-- ... Data.Swagger.Internal.Schema.$dmdeclareNamedSchema @BadMixedType
308+-- ... In an equation for ‘declareNamedSchema’:
309+-- ... declareNamedSchema
310+-- ... = Data.Swagger.Internal.Schema.$dmdeclareNamedSchema @BadMixedType
311+-- ... In the instance declaration for ‘ToSchema BadMixedType’
312+#else
313+-- >>> data BadMixedType = ChoiceBool Bool | JustTag deriving Generic
314+-- >>> instance ToSchema BadMixedType
315+-- ...
316+-- ... error:
317+-- ... • Cannot derive Generic-based Swagger Schema for BadMixedType
318+-- ... BadMixedType is a mixed sum type (has both unit and non-unit constructors).
319+-- ... Swagger does not have a good representation for these types.
320+-- ... Use genericDeclareNamedSchemaUnrestricted if you want to derive schema
321+-- ... that matches aeson's Generic-based toJSON,
322+-- ... but that's not supported by some Swagger tools.
323+-- ... • In the expression:
324+-- ... Data.Swagger.Internal.Schema.$dmdeclareNamedSchema @BadMixedType
325+-- ... In an equation for ‘declareNamedSchema’:
326+-- ... declareNamedSchema
327+-- ... = Data.Swagger.Internal.Schema.$dmdeclareNamedSchema @BadMixedType
328+-- ... In the instance declaration for ‘ToSchema BadMixedType’
329+#endif
330+--
331+-- We can use 'genericDeclareNamedSchemaUnrestricted' to try our best to represent this type as a Swagger Schema and match 'ToJSON':
332+--
333+-- >>> data BadMixedType = ChoiceBool Bool | JustTag deriving Generic
334+-- >>> instance ToSchema BadMixedType where declareNamedSchema = genericDeclareNamedSchemaUnrestricted defaultSchemaOptions
335+-- >>> instance ToJSON BadMixedType
258336--
259337
338+-- $manipulation
339+-- Sometimes you have to work with an imported or generated @'Swagger'@.
340+-- For instance, <servant-swagger http://hackage.haskell.org/package/servant-swagger> generates basic @'Swagger'@
341+-- for a type-level servant API.
342+--
343+-- Lenses and prisms can be used to manipulate such specification to add additional information, tags, extra responses, etc.
344+-- To facilitate common needs, @"Data.Swagger.Operation"@ module provides useful helpers.
345+
346+-- $validation
347+-- While @'ToParamSchema'@ and @'ToSchema'@ provide means to easily obtain schemas for Haskell types,
348+-- there is no static mechanism to ensure those instances correspond to the @'ToHttpApiData'@ or @'ToJSON'@ instances.
349+--
350+-- @"Data.Swagger.Schema.Validation"@ addresses @'ToJSON'@/@'ToSchema'@ validation.
src/Data/Swagger/Declare.hs+83−5
@@ -2,15 +2,33 @@
22{-# LANGUAGE FlexibleInstances #-}
33{-# LANGUAGE FunctionalDependencies #-}
44{-# LANGUAGE MultiParamTypeClasses #-}
5+{-# LANGUAGE UndecidableInstances #-}
6+-- |
7+-- Module: Data.Swagger.Declare
8+-- Maintainer: Nickolay Kudasov <nickolay@getshoptv.com>
9+-- Stability: experimental
10+--
11+-- Declare monad transformer and associated functions.
512module Data.Swagger.Declare where
613
714import Prelude ()
815import Prelude.Compat
916
1017import Control.Monad
18+import Control.Monad.Cont (ContT)
19+import Control.Monad.List (ListT)
20+import Control.Monad.Reader (ReaderT)
1121import Control.Monad.Trans
22+import Control.Monad.Trans.Except (ExceptT)
23+import Control.Monad.Trans.Identity (IdentityT)
24+import Control.Monad.Trans.Maybe (MaybeT)
25+import Control.Monad.Trans.State.Lazy as Lazy
26+import Control.Monad.Trans.State.Strict as Strict
27+import Control.Monad.Trans.RWS.Lazy as Lazy
28+import Control.Monad.Trans.RWS.Strict as Strict
29+import Control.Monad.Trans.Writer.Lazy as Lazy
30+import Control.Monad.Trans.Writer.Strict as Strict
1231import Data.Functor.Identity
13−import Data.Monoid
1432
1533-- | A declare monad transformer parametrized by:
1634--
@@ -31,15 +49,15 @@ instance (Applicative m, Monad m, Monoid d) => Applicative (DeclareT d m) where
3149 pure x = DeclareT (\_ -> pure (mempty, x))
3250 DeclareT df <*> DeclareT dx = DeclareT $ \d -> do
3351 ~(d', f) <- df d
34− ~(d'', x) <- dx (d <> d')
35− return (d' <> d'', f x)
52+ ~(d'', x) <- dx (mappend d d')
53+ return (mappend d' d'', f x)
3654
3755instance (Applicative m, Monad m, Monoid d) => Monad (DeclareT d m) where
3856 return x = DeclareT (\_ -> pure (mempty, x))
3957 DeclareT dx >>= f = DeclareT $ \d -> do
4058 ~(d', x) <- dx d
41− ~(d'', y) <- runDeclareT (f x) (d <> d')
42− return (d' <> d'', y)
59+ ~(d'', y) <- runDeclareT (f x) (mappend d d')
60+ return (mappend d' d'', y)
4361
4462instance Monoid d => MonadTrans (DeclareT d) where
4563 lift m = DeclareT (\_ -> (,) mempty `liftM` m)
@@ -71,6 +89,13 @@ instance (Applicative m, Monad m, Monoid d) => MonadDeclare d (DeclareT d m) whe
7189 declare d = DeclareT (\_ -> return (d, ()))
7290 look = DeclareT (\d -> return (mempty, d))
7391
92+-- | Lift a computation from the simple Declare monad.
93+liftDeclare :: MonadDeclare d m => Declare d a -> m a
94+liftDeclare da = do
95+ (d', a) <- looks (runDeclare da)
96+ declare d'
97+ pure a
98+
7499-- | Retrieve a function of all the output so far.
75100looks :: MonadDeclare d m => (d -> a) -> m a
76101looks f = f <$> look
@@ -119,3 +144,56 @@ execDeclare m = runIdentity . execDeclareT m
119144undeclare :: Monoid d => Declare d a -> a
120145undeclare = runIdentity . undeclareT
121146
147+-- ---------------------------------------------------------------------------
148+-- Instances for other mtl transformers
149+--
150+-- All of these instances need UndecidableInstances,
151+-- because they do not satisfy the coverage condition.
152+
153+instance MonadDeclare d m => MonadDeclare d (ContT r m) where
154+ declare = lift . declare
155+ look = lift look
156+
157+instance MonadDeclare d m => MonadDeclare d (ExceptT e m) where
158+ declare = lift . declare
159+ look = lift look
160+
161+instance MonadDeclare d m => MonadDeclare d (IdentityT m) where
162+ declare = lift . declare
163+ look = lift look
164+
165+instance MonadDeclare d m => MonadDeclare d (ListT m) where
166+ declare = lift . declare
167+ look = lift look
168+
169+instance MonadDeclare d m => MonadDeclare d (MaybeT m) where
170+ declare = lift . declare
171+ look = lift look
172+
173+instance MonadDeclare d m => MonadDeclare d (ReaderT r m) where
174+ declare = lift . declare
175+ look = lift look
176+
177+instance (Monoid w, MonadDeclare d m) => MonadDeclare d (Lazy.RWST r w s m) where
178+ declare = lift . declare
179+ look = lift look
180+
181+instance (Monoid w, MonadDeclare d m) => MonadDeclare d (Strict.RWST r w s m) where
182+ declare = lift . declare
183+ look = lift look
184+
185+instance MonadDeclare d m => MonadDeclare d (Lazy.StateT s m) where
186+ declare = lift . declare
187+ look = lift look
188+
189+instance MonadDeclare d m => MonadDeclare d (Strict.StateT s m) where
190+ declare = lift . declare
191+ look = lift look
192+
193+instance (Monoid w, MonadDeclare d m) => MonadDeclare d (Lazy.WriterT w m) where
194+ declare = lift . declare
195+ look = lift look
196+
197+instance (Monoid w, MonadDeclare d m) => MonadDeclare d (Strict.WriterT w m) where
198+ declare = lift . declare
199+ look = lift look
src/Data/Swagger/Internal.hs+403−144
@@ -1,5 +1,7 @@
11{-# LANGUAGE CPP #-}
2+{-# LANGUAGE DataKinds #-}
23{-# LANGUAGE DeriveDataTypeable #-}
4+{-# LANGUAGE DeriveFunctor #-}
35{-# LANGUAGE DeriveGeneric #-}
46{-# LANGUAGE DeriveTraversable #-}
57{-# LANGUAGE FlexibleContexts #-}
@@ -10,36 +12,66 @@
1012{-# LANGUAGE RecordWildCards #-}
1113{-# LANGUAGE ScopedTypeVariables #-}
1214{-# LANGUAGE StandaloneDeriving #-}
15+{-# LANGUAGE TemplateHaskell #-}
16+{-# LANGUAGE TypeFamilies #-}
1317{-# LANGUAGE UndecidableInstances #-}
18+#if __GLASGOW_HASKELL__ <710
19+{-# LANGUAGE PolyKinds #-}
20+#endif
1421#include "overlapping-compat.h"
1522module Data.Swagger.Internal where
1623
1724import Prelude ()
1825import Prelude.Compat
1926
27+import Control.Lens ((&), (.~), (?~))
2028import Control.Applicative
21−import Control.Monad
2229import Data.Aeson
2330import qualified Data.Aeson.Types as JSON
2431import Data.Data (Data(..), Typeable, mkConstr, mkDataType, Fixity(..), Constr, DataType, constrIndex)
25−import Data.HashMap.Strict (HashMap)
32+import Data.Hashable (Hashable)
2633import qualified Data.HashMap.Strict as HashMap
34+import Data.HashSet.InsOrd (InsOrdHashSet)
2735import Data.Map (Map)
2836import qualified Data.Map as Map
29−import Data.Monoid
37+import Data.Monoid (Monoid (..))
38+import Data.Semigroup.Compat (Semigroup (..))
3039import Data.Scientific (Scientific)
31−import Data.String (fromString)
40+import Data.String (IsString(..))
3241import Data.Text (Text)
3342import qualified Data.Text as Text
3443import GHC.Generics (Generic)
35−import Network (HostName, PortNumber)
44+import Network.Socket (HostName, PortNumber)
3645import Network.HTTP.Media (MediaType)
3746import Text.Read (readMaybe)
3847
48+import Data.HashMap.Strict.InsOrd (InsOrdHashMap)
49+import qualified Data.HashMap.Strict.InsOrd as InsOrdHashMap
50+
51+import Generics.SOP.TH (deriveGeneric)
52+import Data.Swagger.Internal.AesonUtils (sopSwaggerGenericToJSON
53+ ,sopSwaggerGenericToJSONWithOpts
54+ ,sopSwaggerGenericParseJSON
55+ ,HasSwaggerAesonOptions(..)
56+ ,AesonDefaultValue(..)
57+ ,mkSwaggerAesonOptions
58+ ,saoAdditionalPairs
59+ ,saoSubObject)
3960import Data.Swagger.Internal.Utils
4061
62+#if MIN_VERSION_aeson(0,10,0)
63+import Data.Swagger.Internal.AesonUtils (sopSwaggerGenericToEncoding)
64+#define DEFINE_TOENCODING toEncoding = sopSwaggerGenericToEncoding
65+#else
66+#define DEFINE_TOENCODING
67+#endif
68+
69+-- $setup
70+-- >>> :seti -XDataKinds
71+-- >>> import Data.Aeson
72+
4173-- | A list of definitions that can be used in references.
42−type Definitions = HashMap Text
74+type Definitions = InsOrdHashMap Text
4375
4476-- | This is the root document object for the API specification.
4577data Swagger = Swagger
@@ -71,7 +103,7 @@ data Swagger = Swagger
71103 -- | The available paths and operations for the API.
72104 -- Holds the relative paths to the individual endpoints.
73105 -- The path is appended to the @'basePath'@ in order to construct the full URL.
74− , _swaggerPaths :: HashMap FilePath PathItem
106+ , _swaggerPaths :: InsOrdHashMap FilePath PathItem
75107
76108 -- | An object to hold data types produced and consumed by operations.
77109 , _swaggerDefinitions :: Definitions Schema
@@ -85,7 +117,7 @@ data Swagger = Swagger
85117 , _swaggerResponses :: Definitions Response
86118
87119 -- | Security scheme definitions that can be used across the specification.
88− , _swaggerSecurityDefinitions :: Definitions SecurityScheme
120+ , _swaggerSecurityDefinitions :: SecurityDefinitions
89121
90122 -- | A declaration of which security schemes are applied for the API as a whole.
91123 -- The list of values describes alternative security schemes that can be used
@@ -98,7 +130,7 @@ data Swagger = Swagger
98130 -- Not all tags that are used by the Operation Object must be declared.
99131 -- The tags that are not declared may be organized randomly or based on the tools' logic.
100132 -- Each tag name in the list MUST be unique.
101− , _swaggerTags :: [Tag]
133+ , _swaggerTags :: InsOrdHashSet Tag
102134
103135 -- | Additional external documentation.
104136 , _swaggerExternalDocs :: Maybe ExternalDocs
@@ -150,12 +182,18 @@ data License = License
150182 , _licenseUrl :: Maybe URL
151183 } deriving (Eq, Show, Generic, Data, Typeable)
152184
185+instance IsString License where
186+ fromString s = License (fromString s) Nothing
187+
153188-- | The host (name or ip) serving the API. It MAY include a port.
154189data Host = Host
155190 { _hostName :: HostName -- ^ Host name.
156191 , _hostPort :: Maybe PortNumber -- ^ Optional port.
157192 } deriving (Eq, Show, Generic, Typeable)
158193
194+instance IsString Host where
195+ fromString s = Host s Nothing
196+
159197hostConstr :: Constr
160198hostConstr = mkConstr hostDataType "Host" [] Prefix
161199
@@ -214,7 +252,7 @@ data PathItem = PathItem
214252data Operation = Operation
215253 { -- | A list of tags for API documentation control.
216254 -- Tags can be used for logical grouping of operations by resources or any other qualifier.
217− _operationTags :: [TagName]
255+ _operationTags :: InsOrdHashSet TagName
218256
219257 -- | A short summary of what the operation does.
220258 -- For maximum readability in the swagger-ui, this field SHOULD be less than 120 characters.
@@ -271,7 +309,7 @@ data Operation = Operation
271309 } deriving (Eq, Show, Generic, Data, Typeable)
272310
273311newtype MimeList = MimeList { getMimeList :: [MediaType] }
274− deriving (Eq, Show, Monoid, Typeable)
312+ deriving (Eq, Show, Semigroup, Monoid, Typeable)
275313
276314mimeListConstr :: Constr
277315mimeListConstr = mkConstr mimeListDataType "MimeList" ["getMimeList"] Prefix
@@ -322,8 +360,8 @@ data ParamOtherSchema = ParamOtherSchema
322360 -- Default value is @False@.
323361 , _paramOtherSchemaAllowEmptyValue :: Maybe Bool
324362
325− , _paramOtherSchemaParamSchema :: ParamSchema ParamOtherSchema
326− } deriving (Eq, Show, Generic, Data, Typeable)
363+ , _paramOtherSchemaParamSchema :: ParamSchema 'SwaggerKindParamOtherSchema
364+ } deriving (Eq, Show, Generic, Typeable, Data)
327365
328366-- | Items for @'SwaggerArray'@ schemas.
329367--
@@ -336,9 +374,9 @@ data ParamOtherSchema = ParamOtherSchema
336374--
337375-- @'SwaggerItemsArray'@ should be used to specify tuple @'Schema'@s.
338376data SwaggerItems t where
339− SwaggerItemsPrimitive :: Maybe (CollectionFormat t) -> ParamSchema t -> SwaggerItems t
340− SwaggerItemsObject :: Referenced Schema -> SwaggerItems Schema
341− SwaggerItemsArray :: [Referenced Schema] -> SwaggerItems Schema
377+ SwaggerItemsPrimitive :: Maybe (CollectionFormat k) -> ParamSchema k-> SwaggerItems k
378+ SwaggerItemsObject :: Referenced Schema -> SwaggerItems 'SwaggerKindSchema
379+ SwaggerItemsArray :: [Referenced Schema] -> SwaggerItems 'SwaggerKindSchema
342380 deriving (Typeable)
343381
344382deriving instance Eq (SwaggerItems t)
@@ -348,17 +386,66 @@ deriving instance Show (SwaggerItems t)
348386swaggerItemsPrimitiveConstr :: Constr
349387swaggerItemsPrimitiveConstr = mkConstr swaggerItemsDataType "SwaggerItemsPrimitive" [] Prefix
350388
389+swaggerItemsObjectConstr :: Constr
390+swaggerItemsObjectConstr = mkConstr swaggerItemsDataType "SwaggerItemsObject" [] Prefix
391+
392+swaggerItemsArrayConstr :: Constr
393+swaggerItemsArrayConstr = mkConstr swaggerItemsDataType "SwaggerItemsArray" [] Prefix
394+
351395swaggerItemsDataType :: DataType
352396swaggerItemsDataType = mkDataType "Data.Swagger.SwaggerItems" [swaggerItemsPrimitiveConstr]
353397
354−instance OVERLAPPABLE_ Data t => Data (SwaggerItems t) where
398+-- Note: unfortunately we have to write these Data instances by hand,
399+-- to get better contexts / avoid duplicate name when using standalone deriving
400+
401+instance Data t => Data (SwaggerItems ('SwaggerKindNormal t)) where
402+ -- TODO: define gfoldl
355403 gunfold k z c = case constrIndex c of
356404 1 -> k (k (z SwaggerItemsPrimitive))
357405 _ -> error $ "Data.Data.gunfold: Constructor " ++ show c ++ " is not of type (SwaggerItems t)."
358406 toConstr _ = swaggerItemsPrimitiveConstr
359407 dataTypeOf _ = swaggerItemsDataType
360408
361−deriving instance Data (SwaggerItems Schema)
409+-- SwaggerItems SwaggerKindParamOtherSchema can be constructed using SwaggerItemsPrimitive only
410+instance Data (SwaggerItems 'SwaggerKindParamOtherSchema) where
411+ -- TODO: define gfoldl
412+ gunfold k z c = case constrIndex c of
413+ 1 -> k (k (z SwaggerItemsPrimitive))
414+ _ -> error $ "Data.Data.gunfold: Constructor " ++ show c ++ " is not of type (SwaggerItems SwaggerKindParamOtherSchema)."
415+ toConstr _ = swaggerItemsPrimitiveConstr
416+ dataTypeOf _ = swaggerItemsDataType
417+
418+instance Data (SwaggerItems 'SwaggerKindSchema) where
419+ gfoldl _ _ (SwaggerItemsPrimitive _ _) = error $ " Data.Data.gfoldl: Constructor SwaggerItemsPrimitive used to construct SwaggerItems SwaggerKindSchema"
420+ gfoldl k z (SwaggerItemsObject ref) = z SwaggerItemsObject `k` ref
421+ gfoldl k z (SwaggerItemsArray ref) = z SwaggerItemsArray `k` ref
422+
423+ gunfold k z c = case constrIndex c of
424+ 2 -> k (z SwaggerItemsObject)
425+ 3 -> k (z SwaggerItemsArray)
426+ _ -> error $ "Data.Data.gunfold: Constructor " ++ show c ++ " is not of type (SwaggerItems SwaggerKindSchema)."
427+
428+ toConstr (SwaggerItemsPrimitive _ _) = error "Not supported"
429+ toConstr (SwaggerItemsObject _) = swaggerItemsObjectConstr
430+ toConstr (SwaggerItemsArray _) = swaggerItemsArrayConstr
431+
432+ dataTypeOf _ = swaggerItemsDataType
433+
434+-- | Type used as a kind to avoid overlapping instances.
435+data SwaggerKind t
436+ = SwaggerKindNormal t
437+ | SwaggerKindParamOtherSchema
438+ | SwaggerKindSchema
439+ deriving (Typeable)
440+
441+deriving instance Typeable 'SwaggerKindNormal
442+deriving instance Typeable 'SwaggerKindParamOtherSchema
443+deriving instance Typeable 'SwaggerKindSchema
444+
445+type family SwaggerKindType (k :: SwaggerKind *) :: *
446+type instance SwaggerKindType ('SwaggerKindNormal t) = t
447+type instance SwaggerKindType 'SwaggerKindSchema = Schema
448+type instance SwaggerKindType 'SwaggerKindParamOtherSchema = ParamOtherSchema
362449
363450data SwaggerType t where
364451 SwaggerString :: SwaggerType t
@@ -366,9 +453,9 @@ data SwaggerType t where
366453 SwaggerInteger :: SwaggerType t
367454 SwaggerBoolean :: SwaggerType t
368455 SwaggerArray :: SwaggerType t
369− SwaggerFile :: SwaggerType ParamOtherSchema
370− SwaggerNull :: SwaggerType Schema
371− SwaggerObject :: SwaggerType Schema
456+ SwaggerFile :: SwaggerType 'SwaggerKindParamOtherSchema
457+ SwaggerNull :: SwaggerType 'SwaggerKindSchema
458+ SwaggerObject :: SwaggerType 'SwaggerKindSchema
372459 deriving (Typeable)
373460
374461deriving instance Eq (SwaggerType t)
@@ -377,33 +464,33 @@ deriving instance Show (SwaggerType t)
377464swaggerTypeConstr :: Data (SwaggerType t) => SwaggerType t -> Constr
378465swaggerTypeConstr t = mkConstr (dataTypeOf t) (show t) [] Prefix
379466
380−swaggerTypeDataType :: Data (SwaggerType t) => SwaggerType t -> DataType
467+swaggerTypeDataType :: {- Data (SwaggerType t) => -} SwaggerType t -> DataType
381468swaggerTypeDataType _ = mkDataType "Data.Swagger.SwaggerType" swaggerTypeConstrs
382469
383−swaggerCommonTypes :: [SwaggerType t]
470+swaggerCommonTypes :: [SwaggerType k]
384471swaggerCommonTypes = [SwaggerString, SwaggerNumber, SwaggerInteger, SwaggerBoolean, SwaggerArray]
385472
386−swaggerParamTypes :: [SwaggerType ParamOtherSchema]
473+swaggerParamTypes :: [SwaggerType 'SwaggerKindParamOtherSchema]
387474swaggerParamTypes = swaggerCommonTypes ++ [SwaggerFile]
388475
389−swaggerSchemaTypes :: [SwaggerType Schema]
476+swaggerSchemaTypes :: [SwaggerType 'SwaggerKindSchema]
390477swaggerSchemaTypes = swaggerCommonTypes ++ [error "SwaggerFile is invalid SwaggerType Schema", SwaggerNull, SwaggerObject]
391478
392479swaggerTypeConstrs :: [Constr]
393−swaggerTypeConstrs = map swaggerTypeConstr (swaggerCommonTypes :: [SwaggerType Schema])
480+swaggerTypeConstrs = map swaggerTypeConstr (swaggerCommonTypes :: [SwaggerType 'SwaggerKindSchema])
394481 ++ [swaggerTypeConstr SwaggerFile, swaggerTypeConstr SwaggerNull, swaggerTypeConstr SwaggerObject]
395482
396−instance OVERLAPPABLE_ Typeable t => Data (SwaggerType t) where
483+instance Typeable t => Data (SwaggerType ('SwaggerKindNormal t)) where
397484 gunfold = gunfoldEnum "SwaggerType" swaggerCommonTypes
398485 toConstr = swaggerTypeConstr
399486 dataTypeOf = swaggerTypeDataType
400487
401−instance OVERLAPPABLE_ Data (SwaggerType ParamOtherSchema) where
488+instance Data (SwaggerType 'SwaggerKindParamOtherSchema) where
402489 gunfold = gunfoldEnum "SwaggerType ParamOtherSchema" swaggerParamTypes
403490 toConstr = swaggerTypeConstr
404491 dataTypeOf = swaggerTypeDataType
405492
406−instance OVERLAPPABLE_ Data (SwaggerType Schema) where
493+instance Data (SwaggerType 'SwaggerKindSchema) where
407494 gunfold = gunfoldEnum "SwaggerType Schema" swaggerSchemaTypes
408495 toConstr = swaggerTypeConstr
409496 dataTypeOf = swaggerTypeDataType
@@ -443,7 +530,7 @@ data CollectionFormat t where
443530 -- Corresponds to multiple parameter instances
444531 -- instead of multiple values for a single instance @foo=bar&foo=baz@.
445532 -- This is valid only for parameters in @'ParamQuery'@ or @'ParamFormData'@.
446− CollectionMulti :: CollectionFormat ParamOtherSchema
533+ CollectionMulti :: CollectionFormat 'SwaggerKindParamOtherSchema
447534 deriving (Typeable)
448535
449536deriving instance Eq (CollectionFormat t)
@@ -459,12 +546,12 @@ collectionFormatDataType = mkDataType "Data.Swagger.CollectionFormat" $
459546collectionCommonFormats :: [CollectionFormat t]
460547collectionCommonFormats = [ CollectionCSV, CollectionSSV, CollectionTSV, CollectionPipes ]
461548
462−instance OVERLAPPABLE_ Data t => Data (CollectionFormat t) where
549+instance Data t => Data (CollectionFormat ('SwaggerKindNormal t)) where
463550 gunfold = gunfoldEnum "CollectionFormat" collectionCommonFormats
464551 toConstr = collectionFormatConstr
465552 dataTypeOf _ = collectionFormatDataType
466553
467−deriving instance OVERLAPPABLE_ Data (CollectionFormat ParamOtherSchema)
554+deriving instance Data (CollectionFormat 'SwaggerKindParamOtherSchema)
468555
469556type ParamName = Text
470557
@@ -473,9 +560,9 @@ data Schema = Schema
473560 , _schemaDescription :: Maybe Text
474561 , _schemaRequired :: [ParamName]
475562
476− , _schemaAllOf :: Maybe [Schema]
477− , _schemaProperties :: HashMap Text (Referenced Schema)
478− , _schemaAdditionalProperties :: Maybe Schema
563+ , _schemaAllOf :: Maybe [Referenced Schema]
564+ , _schemaProperties :: InsOrdHashMap Text (Referenced Schema)
565+ , _schemaAdditionalProperties :: Maybe AdditionalProperties
479566
480567 , _schemaDiscriminator :: Maybe Text
481568 , _schemaReadOnly :: Maybe Bool
@@ -486,7 +573,7 @@ data Schema = Schema
486573 , _schemaMaxProperties :: Maybe Integer
487574 , _schemaMinProperties :: Maybe Integer
488575
489− , _schemaParamSchema :: ParamSchema Schema
576+ , _schemaParamSchema :: ParamSchema 'SwaggerKindSchema
490577 } deriving (Eq, Show, Generic, Data, Typeable)
491578
492579-- | A @'Schema'@ with an optional name.
@@ -496,7 +583,10 @@ data NamedSchema = NamedSchema
496583 , _namedSchemaSchema :: Schema
497584 } deriving (Eq, Show, Generic, Data, Typeable)
498585
499−data ParamSchema t = ParamSchema
586+-- | Regex pattern for @string@ type.
587+type Pattern = Text
588+
589+data ParamSchema (t :: SwaggerKind *) = ParamSchema
500590 { -- | Declares the value of the parameter that the server will use if none is provided,
501591 -- for example a @"count"@ to control the number of results per page might default to @100@
502592 -- if not supplied by the client in the request.
@@ -504,7 +594,7 @@ data ParamSchema t = ParamSchema
504594 -- Unlike JSON Schema this value MUST conform to the defined type for this parameter.
505595 _paramSchemaDefault :: Maybe Value
506596
507− , _paramSchemaType :: SwaggerType t
597+ , _paramSchemaType :: Maybe (SwaggerType t)
508598 , _paramSchemaFormat :: Maybe Format
509599 , _paramSchemaItems :: Maybe (SwaggerItems t)
510600 , _paramSchemaMaximum :: Maybe Scientific
@@ -513,7 +603,7 @@ data ParamSchema t = ParamSchema
513603 , _paramSchemaExclusiveMinimum :: Maybe Bool
514604 , _paramSchemaMaxLength :: Maybe Integer
515605 , _paramSchemaMinLength :: Maybe Integer
516− , _paramSchemaPattern :: Maybe Text
606+ , _paramSchemaPattern :: Maybe Pattern
517607 , _paramSchemaMaxItems :: Maybe Integer
518608 , _paramSchemaMinItems :: Maybe Integer
519609 , _paramSchemaUniqueItems :: Maybe Bool
@@ -521,7 +611,7 @@ data ParamSchema t = ParamSchema
521611 , _paramSchemaMultipleOf :: Maybe Scientific
522612 } deriving (Eq, Show, Generic, Typeable)
523613
524−deriving instance (Data t, Data (SwaggerType t), Data (SwaggerItems t)) => Data (ParamSchema t)
614+deriving instance (Typeable k, Data (Maybe (SwaggerType k)), Data (SwaggerItems k)) => Data (ParamSchema k)
525615
526616data Xml = Xml
527617 { -- | Replaces the name of the element/attribute used for the described schema property.
@@ -563,7 +653,7 @@ data Responses = Responses
563653
564654 -- | Any HTTP status code can be used as the property name (one property per HTTP status code).
565655 -- Describes the expected response for those HTTP status codes.
566− , _responsesResponses :: HashMap HttpStatusCode (Referenced Response)
656+ , _responsesResponses :: InsOrdHashMap HttpStatusCode (Referenced Response)
567657 } deriving (Eq, Show, Generic, Data, Typeable)
568658
569659type HttpStatusCode = Int
@@ -582,19 +672,22 @@ data Response = Response
582672 , _responseSchema :: Maybe (Referenced Schema)
583673
584674 -- | A list of headers that are sent with the response.
585− , _responseHeaders :: HashMap HeaderName Header
675+ , _responseHeaders :: InsOrdHashMap HeaderName Header
586676
587677 -- | An example of the response message.
588678 , _responseExamples :: Maybe Example
589679 } deriving (Eq, Show, Generic, Data, Typeable)
590680
681+instance IsString Response where
682+ fromString s = Response (fromString s) Nothing mempty Nothing
683+
591684type HeaderName = Text
592685
593686data Header = Header
594687 { -- | A short description of the header.
595688 _headerDescription :: Maybe Text
596689
597− , _headerParamSchema :: ParamSchema Header
690+ , _headerParamSchema :: ParamSchema ('SwaggerKindNormal Header)
598691 } deriving (Eq, Show, Generic, Data, Typeable)
599692
600693data Example = Example { getExample :: Map MediaType Value }
@@ -645,7 +738,7 @@ data OAuth2Params = OAuth2Params
645738 _oauth2Flow :: OAuth2Flow
646739
647740 -- | The available scopes for the OAuth2 security scheme.
648− , _oauth2Scopes :: HashMap Text Text
741+ , _oauth2Scopes :: InsOrdHashMap Text Text
649742 } deriving (Eq, Show, Generic, Data, Typeable)
650743
651744data SecuritySchemeType
@@ -662,12 +755,28 @@ data SecurityScheme = SecurityScheme
662755 , _securitySchemeDescription :: Maybe Text
663756 } deriving (Eq, Show, Generic, Data, Typeable)
664757
758+
759+-- | merge scopes of two OAuth2 security schemes when their flows are identical.
760+-- In other case returns first security scheme
761+mergeSecurityScheme :: SecurityScheme -> SecurityScheme -> SecurityScheme
762+mergeSecurityScheme s1@(SecurityScheme (SecuritySchemeOAuth2 (OAuth2Params flow1 scopes1)) desc)
763+ s2@(SecurityScheme (SecuritySchemeOAuth2 (OAuth2Params flow2 scopes2)) _)
764+ = if flow1 == flow2 then
765+ SecurityScheme (SecuritySchemeOAuth2 (OAuth2Params flow1 (scopes1 <> scopes2))) desc
766+ else
767+ s1
768+mergeSecurityScheme s1 _ = s1
769+
770+newtype SecurityDefinitions
771+ = SecurityDefinitions (Definitions SecurityScheme)
772+ deriving (Eq, Show, Generic, Data, Typeable)
773+
665774-- | Lists the required security schemes to execute this operation.
666775-- The object can have multiple security schemes declared in it which are all required
667776-- (that is, there is a logical AND between the schemes).
668777newtype SecurityRequirement = SecurityRequirement
669− { getSecurityRequirement :: HashMap Text [Text]
670− } deriving (Eq, Read, Show, Monoid, ToJSON, FromJSON, Data, Typeable)
778+ { getSecurityRequirement :: InsOrdHashMap Text [Text]
779+ } deriving (Eq, Read, Show, Semigroup, Monoid, ToJSON, FromJSON, Data, Typeable)
671780
672781-- | Tag name.
673782type TagName = Text
@@ -684,7 +793,12 @@ data Tag = Tag
684793
685794 -- | Additional external documentation for this tag.
686795 , _tagExternalDocs :: Maybe ExternalDocs
687− } deriving (Eq, Show, Generic, Data, Typeable)
796+ } deriving (Eq, Ord, Show, Generic, Data, Typeable)
797+
798+instance Hashable Tag
799+
800+instance IsString Tag where
801+ fromString s = Tag (fromString s) Nothing Nothing
688802
689803-- | Allows referencing an external resource for extended documentation.
690804data ExternalDocs = ExternalDocs
@@ -694,7 +808,9 @@ data ExternalDocs = ExternalDocs
694808
695809 -- | The URL for the target documentation.
696810 , _externalDocsUrl :: URL
697− } deriving (Eq, Show, Generic, Data, Typeable)
811+ } deriving (Eq, Ord, Show, Generic, Data, Typeable)
812+
813+instance Hashable ExternalDocs
698814
699815-- | A simple object to allow referencing other definitions in the specification.
700816-- It can be used to reference parameters and responses that are defined at the top level for reuse.
@@ -704,69 +820,116 @@ newtype Reference = Reference { getReference :: Text }
704820data Referenced a
705821 = Ref Reference
706822 | Inline a
707− deriving (Eq, Show, Data, Typeable)
823+ deriving (Eq, Show, Functor, Data, Typeable)
824+
825+instance IsString a => IsString (Referenced a) where
826+ fromString = Inline . fromString
827+
828+newtype URL = URL { getUrl :: Text } deriving (Eq, Ord, Show, Hashable, ToJSON, FromJSON, Data, Typeable)
708829
709−newtype URL = URL { getUrl :: Text } deriving (Eq, Show, ToJSON, FromJSON, Data, Typeable)
830+data AdditionalProperties
831+ = AdditionalPropertiesAllowed Bool
832+ | AdditionalPropertiesSchema (Referenced Schema)
833+ deriving (Eq, Show, Data, Typeable)
710834
711835-- =======================================================================
712836-- Monoid instances
713837-- =======================================================================
714838
839+instance Semigroup Swagger where
840+ (<>) = genericMappend
715841instance Monoid Swagger where
716842 mempty = genericMempty
717− mappend = genericMappend
843+ mappend = (<>)
718844
845+instance Semigroup Info where
846+ (<>) = genericMappend
719847instance Monoid Info where
720848 mempty = genericMempty
721− mappend = genericMappend
849+ mappend = (<>)
722850
851+instance Semigroup Contact where
852+ (<>) = genericMappend
723853instance Monoid Contact where
724854 mempty = genericMempty
725− mappend = genericMappend
855+ mappend = (<>)
726856
857+instance Semigroup PathItem where
858+ (<>) = genericMappend
727859instance Monoid PathItem where
728860 mempty = genericMempty
729− mappend = genericMappend
861+ mappend = (<>)
730862
863+instance Semigroup Schema where
864+ (<>) = genericMappend
731865instance Monoid Schema where
732866 mempty = genericMempty
733− mappend = genericMappend
867+ mappend = (<>)
734868
869+instance Semigroup (ParamSchema t) where
870+ (<>) = genericMappend
735871instance Monoid (ParamSchema t) where
736872 mempty = genericMempty
737− mappend = genericMappend
873+ mappend = (<>)
738874
875+instance Semigroup Param where
876+ (<>) = genericMappend
739877instance Monoid Param where
740878 mempty = genericMempty
741− mappend = genericMappend
879+ mappend = (<>)
742880
881+instance Semigroup ParamOtherSchema where
882+ (<>) = genericMappend
743883instance Monoid ParamOtherSchema where
744884 mempty = genericMempty
745− mappend = genericMappend
885+ mappend = (<>)
746886
887+instance Semigroup Header where
888+ (<>) = genericMappend
747889instance Monoid Header where
748890 mempty = genericMempty
749− mappend = genericMappend
891+ mappend = (<>)
750892
893+instance Semigroup Responses where
894+ (<>) = genericMappend
751895instance Monoid Responses where
752896 mempty = genericMempty
753− mappend = genericMappend
897+ mappend = (<>)
754898
899+instance Semigroup Response where
900+ (<>) = genericMappend
755901instance Monoid Response where
756902 mempty = genericMempty
757− mappend = genericMappend
903+ mappend = (<>)
758904
905+instance Semigroup ExternalDocs where
906+ (<>) = genericMappend
759907instance Monoid ExternalDocs where
760908 mempty = genericMempty
761− mappend = genericMappend
909+ mappend = (<>)
762910
911+instance Semigroup Operation where
912+ (<>) = genericMappend
763913instance Monoid Operation where
764914 mempty = genericMempty
765− mappend = genericMappend
915+ mappend = (<>)
766916
917+instance Semigroup Example where
918+ (<>) = genericMappend
767919instance Monoid Example where
768920 mempty = genericMempty
769− mappend = genericMappend
921+ mappend = (<>)
922+
923+instance Semigroup SecurityScheme where
924+ (<>) = mergeSecurityScheme
925+
926+instance Semigroup SecurityDefinitions where
927+ (SecurityDefinitions sd1) <> (SecurityDefinitions sd2) =
928+ SecurityDefinitions $ InsOrdHashMap.unionWith (<>) sd1 sd2
929+
930+instance Monoid SecurityDefinitions where
931+ mempty = SecurityDefinitions $ InsOrdHashMap.empty
932+ mappend = (<>)
770933
771934-- =======================================================================
772935-- SwaggerMonoid helper instances
@@ -782,6 +945,8 @@ instance SwaggerMonoid Responses
782945instance SwaggerMonoid Response
783946instance SwaggerMonoid ExternalDocs
784947instance SwaggerMonoid Operation
948+instance SwaggerMonoid SecurityDefinitions
949+instance (Eq a, Hashable a) => SwaggerMonoid (InsOrdHashSet a)
785950
786951instance SwaggerMonoid MimeList
787952deriving instance SwaggerMonoid URL
@@ -794,13 +959,13 @@ instance SwaggerMonoid ParamLocation where
794959 swaggerMempty = ParamQuery
795960 swaggerMappend _ y = y
796961
797−instance OVERLAPPING_ SwaggerMonoid (HashMap FilePath PathItem) where
798− swaggerMempty = HashMap.empty
799− swaggerMappend = HashMap.unionWith mappend
962+instance OVERLAPPING_ SwaggerMonoid (InsOrdHashMap FilePath PathItem) where
963+ swaggerMempty = InsOrdHashMap.empty
964+ swaggerMappend = InsOrdHashMap.unionWith mappend
800965
801966instance Monoid a => SwaggerMonoid (Referenced a) where
802967 swaggerMempty = Inline mempty
803− swaggerMappend (Inline x) (Inline y) = Inline (x <> y)
968+ swaggerMappend (Inline x) (Inline y) = Inline (mappend x y)
804969 swaggerMappend _ y = y
805970
806971instance SwaggerMonoid ParamAnySchema where
@@ -894,7 +1059,8 @@ instance ToJSON OAuth2Flow where
8941059 , "tokenUrl" .= tokenUrl ]
8951060
8961061instance ToJSON OAuth2Params where
897− toJSON = omitEmpties . genericToJSONWithSub "flow" (jsonPrefix "oauth2")
1062+ toJSON = sopSwaggerGenericToJSON
1063+ DEFINE_TOENCODING
8981064
8991065instance ToJSON SecuritySchemeType where
9001066 toJSON SecuritySchemeBasic
@@ -907,28 +1073,37 @@ instance ToJSON SecuritySchemeType where
9071073 <+> object [ "type" .= ("oauth2" :: Text) ]
9081074
9091075instance ToJSON Swagger where
910− toJSON = omitEmpties . addVersion . genericToJSON (jsonPrefix "swagger")
911− where
912− addVersion (Object o) = Object (HashMap.insert "swagger" "2.0" o)
913− addVersion _ = error "impossible"
1076+ toJSON = sopSwaggerGenericToJSON
1077+ DEFINE_TOENCODING
9141078
9151079instance ToJSON SecurityScheme where
916− toJSON = genericToJSONWithSub "type" (jsonPrefix "securityScheme")
1080+ toJSON = sopSwaggerGenericToJSON
1081+ DEFINE_TOENCODING
9171082
9181083instance ToJSON Schema where
919− toJSON = omitEmptiesExcept f . genericToJSONWithSub "paramSchema" (jsonPrefix "schema")
920− where
921− f "items" (Array _) = True
922− f _ _ = False
1084+ toJSON = sopSwaggerGenericToJSON
1085+ DEFINE_TOENCODING
9231086
9241087instance ToJSON Header where
925− toJSON = genericToJSONWithSub "paramSchema" (jsonPrefix "header")
1088+ toJSON = sopSwaggerGenericToJSON
1089+ DEFINE_TOENCODING
9261090
927−instance ToJSON (SwaggerItems t) where
1091+-- | As for nullary schema for 0-arity type constructors, see
1092+-- <https://github.com/GetShopTV/swagger2/issues/167>.
1093+--
1094+-- >>> encode (SwaggerItemsArray [])
1095+-- "{\"example\":[],\"items\":{},\"maxItems\":0}"
1096+--
1097+instance ToJSON (ParamSchema t) => ToJSON (SwaggerItems t) where
9281098 toJSON (SwaggerItemsPrimitive fmt schema) = object
9291099 [ "collectionFormat" .= fmt
9301100 , "items" .= schema ]
9311101 toJSON (SwaggerItemsObject x) = object [ "items" .= x ]
1102+ toJSON (SwaggerItemsArray []) = object
1103+ [ "items" .= object []
1104+ , "maxItems" .= (0 :: Int)
1105+ , "example" .= Array mempty
1106+ ]
9321107 toJSON (SwaggerItemsArray x) = object [ "items" .= x ]
9331108
9341109instance ToJSON Host where
@@ -941,31 +1116,39 @@ instance ToJSON MimeList where
9411116 toJSON (MimeList xs) = toJSON (map show xs)
9421117
9431118instance ToJSON Param where
944− toJSON = genericToJSONWithSub "schema" (jsonPrefix "param")
1119+ toJSON = sopSwaggerGenericToJSON
1120+ DEFINE_TOENCODING
9451121
9461122instance ToJSON ParamAnySchema where
9471123 toJSON (ParamBody s) = object [ "in" .= ("body" :: Text), "schema" .= s ]
9481124 toJSON (ParamOther s) = toJSON s
9491125
9501126instance ToJSON ParamOtherSchema where
951− toJSON = genericToJSONWithSub "paramSchema" (jsonPrefix "paramOtherSchema")
1127+ toJSON = sopSwaggerGenericToJSON
1128+ DEFINE_TOENCODING
9521129
9531130instance ToJSON Responses where
954− toJSON (Responses def rs) = omitEmpties $
955− toJSON (hashMapMapKeys show rs) <+> object [ "default" .= def ]
1131+ toJSON = sopSwaggerGenericToJSON
1132+ DEFINE_TOENCODING
9561133
9571134instance ToJSON Response where
958− toJSON = omitEmpties . genericToJSON (jsonPrefix "response")
1135+ toJSON = sopSwaggerGenericToJSON
1136+ DEFINE_TOENCODING
9591137
9601138instance ToJSON Operation where
961− toJSON = omitEmpties . genericToJSON (jsonPrefix "operation")
1139+ toJSON = sopSwaggerGenericToJSON
1140+ DEFINE_TOENCODING
9621141
9631142instance ToJSON PathItem where
964− toJSON = omitEmpties . genericToJSON (jsonPrefix "pathItem")
1143+ toJSON = sopSwaggerGenericToJSON
1144+ DEFINE_TOENCODING
9651145
9661146instance ToJSON Example where
9671147 toJSON = toJSON . Map.mapKeys show . getExample
9681148
1149+instance ToJSON SecurityDefinitions where
1150+ toJSON (SecurityDefinitions sd) = toJSON sd
1151+
9691152instance ToJSON Reference where
9701153 toJSON (Reference ref) = object [ "$ref" .= ref ]
9711154
@@ -994,11 +1177,14 @@ instance ToJSON (CollectionFormat t) where
9941177 toJSON CollectionPipes = "pipes"
9951178 toJSON CollectionMulti = "multi"
9961179
997−instance ToJSON (ParamSchema t) where
998− toJSON = omitEmptiesExcept f . genericToJSONWithSub "items" (jsonPrefix "paramSchema")
999− where
1000− f "items" (Array _) = True
1001− f _ _ = False
1180+instance ToJSON (ParamSchema k) where
1181+ -- TODO: this is a bit fishy, why we need sub object only in `ToJSON`?
1182+ toJSON = sopSwaggerGenericToJSONWithOpts $
1183+ mkSwaggerAesonOptions "paramSchema" & saoSubObject ?~ "items"
1184+
1185+instance ToJSON AdditionalProperties where
1186+ toJSON (AdditionalPropertiesAllowed b) = toJSON b
1187+ toJSON (AdditionalPropertiesSchema s) = toJSON s
10021188
10031189-- =======================================================================
10041190-- Manual FromJSON instances
@@ -1018,7 +1204,7 @@ instance FromJSON OAuth2Flow where
10181204 parseJSON _ = empty
10191205
10201206instance FromJSON OAuth2Params where
1021− parseJSON = genericParseJSONWithSub "flow" (jsonPrefix "oauth2")
1207+ parseJSON = sopSwaggerGenericParseJSON
10221208
10231209instance FromJSON SecuritySchemeType where
10241210 parseJSON js@(Object o) = do
@@ -1031,57 +1217,65 @@ instance FromJSON SecuritySchemeType where
10311217 parseJSON _ = empty
10321218
10331219instance FromJSON Swagger where
1034− parseJSON js@(Object o) = do
1035− (version :: Text) <- o .: "swagger"
1036− when (version /= "2.0") empty
1037− (genericParseJSON (jsonPrefix "swagger")
1038− `withDefaults` [ "consumes" .= (mempty :: MimeList)
1039− , "produces" .= (mempty :: MimeList)
1040− , "security" .= ([] :: [SecurityRequirement])
1041− , "tags" .= ([] :: [Tag])
1042− , "definitions" .= (mempty :: Definitions Schema)
1043− , "parameters" .= (mempty :: Definitions Param)
1044− , "responses" .= (mempty :: Definitions Response)
1045− , "securityDefinitions" .= (mempty :: Definitions SecurityScheme)
1046− ] ) js
1047− parseJSON _ = empty
1220+ parseJSON = sopSwaggerGenericParseJSON
10481221
10491222instance FromJSON SecurityScheme where
1050− parseJSON = genericParseJSONWithSub "type" (jsonPrefix "securityScheme")
1223+ parseJSON = sopSwaggerGenericParseJSON
10511224
10521225instance FromJSON Schema where
1053− parseJSON = genericParseJSONWithSub "paramSchema" (jsonPrefix "schema")
1054− `withDefaults` [ "properties" .= (mempty :: HashMap Text Schema)
1055− , "required" .= ([] :: [ParamName]) ]
1226+ parseJSON = fmap nullaryCleanup . sopSwaggerGenericParseJSON
1227+ where nullaryCleanup :: Schema -> Schema
1228+ nullaryCleanup s@Schema{_schemaParamSchema=ps} =
1229+ if _paramSchemaItems ps == Just (SwaggerItemsArray [])
1230+ then s { _schemaExample = Nothing
1231+ , _schemaParamSchema = ps { _paramSchemaMaxItems = Nothing } }
1232+ else s
10561233
10571234instance FromJSON Header where
1058− parseJSON = genericParseJSONWithSub "paramSchema" (jsonPrefix "header")
1235+ parseJSON = sopSwaggerGenericParseJSON
10591236
1060−instance OVERLAPPABLE_ (FromJSON (CollectionFormat t), FromJSON (ParamSchema t)) => FromJSON (SwaggerItems t) where
1237+instance (FromJSON (CollectionFormat ('SwaggerKindNormal t)), FromJSON (ParamSchema ('SwaggerKindNormal t))) => FromJSON (SwaggerItems ('SwaggerKindNormal t)) where
10611238 parseJSON = withObject "SwaggerItemsPrimitive" $ \o -> SwaggerItemsPrimitive
10621239 <$> o .:? "collectionFormat"
10631240 <*> (o .: "items" >>= parseJSON)
10641241
1065−instance OVERLAPPABLE_ FromJSON (SwaggerItems Schema) where
1066− parseJSON js@(Object _) = SwaggerItemsObject <$> parseJSON js
1242+instance FromJSON (SwaggerItems 'SwaggerKindParamOtherSchema) where
1243+ parseJSON = withObject "SwaggerItemsPrimitive" $ \o -> SwaggerItemsPrimitive
1244+ <$> o .:? "collectionFormat"
1245+ <*> ((o .: "items" >>= parseJSON) <|> fail ("foo" ++ show o))
1246+
1247+-- |
1248+--
1249+-- >>> decode "{}" :: Maybe (SwaggerItems 'SwaggerKindSchema)
1250+-- Just (SwaggerItemsArray [])
1251+--
1252+-- >>> eitherDecode "{\"$ref\":\"#/definitions/example\"}" :: Either String (SwaggerItems 'SwaggerKindSchema)
1253+-- Right (SwaggerItemsObject (Ref (Reference {getReference = "example"})))
1254+--
1255+-- >>> eitherDecode "[{\"$ref\":\"#/definitions/example\"}]" :: Either String (SwaggerItems 'SwaggerKindSchema)
1256+-- Right (SwaggerItemsArray [Ref (Reference {getReference = "example"})])
1257+--
1258+instance FromJSON (SwaggerItems 'SwaggerKindSchema) where
1259+ parseJSON js@(Object obj)
1260+ | null obj = pure $ SwaggerItemsArray [] -- Nullary schema.
1261+ | otherwise = SwaggerItemsObject <$> parseJSON js
10671262 parseJSON js@(Array _) = SwaggerItemsArray <$> parseJSON js
10681263 parseJSON _ = empty
10691264
10701265instance FromJSON Host where
1071− parseJSON (String s) =
1072− case fromInteger <$> readMaybe portStr of
1073− Nothing | not (null portStr) -> fail $ "Invalid port `" ++ portStr ++ "'"
1074− mport -> pure $ Host host mport
1075− where
1076− (hostText, portText) = Text.breakOn ":" s
1077− [host, portStr] = map Text.unpack [hostText, portText]
1266+ parseJSON (String s) = case map Text.unpack $ Text.split (== ':') s of
1267+ [host] -> return $ Host host Nothing
1268+ [host, port] -> case readMaybe port of
1269+ Nothing -> fail $ "Invalid port `" ++ port ++ "'"
1270+ Just p -> return $ Host host (Just (fromInteger p))
1271+ _ -> fail $ "Invalid host `" ++ Text.unpack s ++ "'"
10781272 parseJSON _ = empty
10791273
10801274instance FromJSON MimeList where
10811275 parseJSON js = (MimeList . map fromString) <$> parseJSON js
10821276
10831277instance FromJSON Param where
1084− parseJSON = genericParseJSONWithSub "schema" (jsonPrefix "param")
1278+ parseJSON = sopSwaggerGenericParseJSON
10851279
10861280instance FromJSON ParamAnySchema where
10871281 parseJSON js@(Object o) = do
@@ -1094,12 +1288,12 @@ instance FromJSON ParamAnySchema where
10941288 parseJSON _ = empty
10951289
10961290instance FromJSON ParamOtherSchema where
1097− parseJSON = genericParseJSONWithSub "paramSchema" (jsonPrefix "paramOtherSchema")
1291+ parseJSON = sopSwaggerGenericParseJSON
10981292
10991293instance FromJSON Responses where
11001294 parseJSON (Object o) = Responses
11011295 <$> o .:? "default"
1102− <*> (parseJSON (Object (HashMap.delete "default" o)) >>= hashMapReadKeys)
1296+ <*> (parseJSON (Object (HashMap.delete "default" o)))
11031297 parseJSON _ = empty
11041298
11051299instance FromJSON Example where
@@ -1108,16 +1302,16 @@ instance FromJSON Example where
11081302 pure $ Example (Map.mapKeys fromString m)
11091303
11101304instance FromJSON Response where
1111− parseJSON = genericParseJSON (jsonPrefix "response")
1112− `withDefaults` [ "headers" .= (mempty :: HashMap HeaderName Header) ]
1305+ parseJSON = sopSwaggerGenericParseJSON
11131306
11141307instance FromJSON Operation where
1115− parseJSON = genericParseJSON (jsonPrefix "operation")
1116− `withDefaults` [ "security" .= ([] :: [SecurityRequirement]) ]
1308+ parseJSON = sopSwaggerGenericParseJSON
11171309
11181310instance FromJSON PathItem where
1119− parseJSON = genericParseJSON (jsonPrefix "pathItem")
1120− `withDefaults` [ "parameters" .= ([] :: [Param]) ]
1311+ parseJSON = sopSwaggerGenericParseJSON
1312+
1313+instance FromJSON SecurityDefinitions where
1314+ parseJSON js = SecurityDefinitions <$> parseJSON js
11211315
11221316instance FromJSON Reference where
11231317 parseJSON (Object o) = Reference <$> o .: "$ref"
@@ -1143,26 +1337,91 @@ instance FromJSON (Referenced Response) where parseJSON = referencedParseJSON "#
11431337instance FromJSON Xml where
11441338 parseJSON = genericParseJSON (jsonPrefix "xml")
11451339
1146−instance FromJSON (SwaggerType Schema) where
1340+instance FromJSON (SwaggerType 'SwaggerKindSchema) where
11471341 parseJSON = parseOneOf [SwaggerString, SwaggerInteger, SwaggerNumber, SwaggerBoolean, SwaggerArray, SwaggerNull, SwaggerObject]
11481342
1149−instance FromJSON (SwaggerType ParamOtherSchema) where
1343+instance FromJSON (SwaggerType 'SwaggerKindParamOtherSchema) where
11501344 parseJSON = parseOneOf [SwaggerString, SwaggerInteger, SwaggerNumber, SwaggerBoolean, SwaggerArray, SwaggerFile]
11511345
1152−instance OVERLAPPABLE_ FromJSON (SwaggerType t) where
1346+instance FromJSON (SwaggerType ('SwaggerKindNormal t)) where
11531347 parseJSON = parseOneOf [SwaggerString, SwaggerInteger, SwaggerNumber, SwaggerBoolean, SwaggerArray]
11541348
1155−instance OVERLAPPABLE_ FromJSON (CollectionFormat t) where
1349+instance FromJSON (CollectionFormat ('SwaggerKindNormal t)) where
11561350 parseJSON = parseOneOf [CollectionCSV, CollectionSSV, CollectionTSV, CollectionPipes]
11571351
1158−instance FromJSON (CollectionFormat ParamOtherSchema) where
1159− parseJSON = parseOneOf [CollectionCSV, CollectionSSV, CollectionTSV, CollectionPipes, CollectionMulti]
1352+-- NOTE: There aren't collections of 'Schema'
1353+--instance FromJSON (CollectionFormat (SwaggerKindSchema)) where
1354+-- parseJSON = parseOneOf [CollectionCSV, CollectionSSV, CollectionTSV, CollectionPipes]
11601355
1161−-- NOTE: The constraints @FromJSON (SwaggerType t)@ and
1162−-- @FromJSON (SwaggerItems t)@ are necessary here!
1163−-- Without the constraint the general instance will be used
1164−-- that only accepts common types (i.e. NOT object, null or file)
1165−-- and primitive array items.
1166−instance (FromJSON (SwaggerType t), FromJSON (SwaggerItems t)) => FromJSON (ParamSchema t) where
1167− parseJSON = genericParseJSONWithSub "items" (jsonPrefix "ParamSchema")
1356+instance FromJSON (CollectionFormat 'SwaggerKindParamOtherSchema) where
1357+ parseJSON = parseOneOf [CollectionCSV, CollectionSSV, CollectionTSV, CollectionPipes, CollectionMulti]
11681358
1359+instance (FromJSON (SwaggerType ('SwaggerKindNormal t)), FromJSON (SwaggerItems ('SwaggerKindNormal t))) => FromJSON (ParamSchema ('SwaggerKindNormal t)) where
1360+ parseJSON = sopSwaggerGenericParseJSON
1361+instance FromJSON (ParamSchema 'SwaggerKindParamOtherSchema) where
1362+ parseJSON = sopSwaggerGenericParseJSON
1363+instance FromJSON (ParamSchema 'SwaggerKindSchema) where
1364+ parseJSON = sopSwaggerGenericParseJSON
1365+
1366+instance FromJSON AdditionalProperties where
1367+ parseJSON (Bool b) = pure $ AdditionalPropertiesAllowed b
1368+ parseJSON js = AdditionalPropertiesSchema <$> parseJSON js
1369+
1370+-------------------------------------------------------------------------------
1371+-- TH splices
1372+-------------------------------------------------------------------------------
1373+
1374+deriveGeneric ''Header
1375+deriveGeneric ''OAuth2Params
1376+deriveGeneric ''Operation
1377+deriveGeneric ''Param
1378+deriveGeneric ''ParamOtherSchema
1379+deriveGeneric ''PathItem
1380+deriveGeneric ''Response
1381+deriveGeneric ''Responses
1382+deriveGeneric ''SecurityScheme
1383+deriveGeneric ''Schema
1384+deriveGeneric ''ParamSchema
1385+deriveGeneric ''Swagger
1386+
1387+instance HasSwaggerAesonOptions Header where
1388+ swaggerAesonOptions _ = mkSwaggerAesonOptions "header" & saoSubObject ?~ "paramSchema"
1389+instance HasSwaggerAesonOptions OAuth2Params where
1390+ swaggerAesonOptions _ = mkSwaggerAesonOptions "oauth2" & saoSubObject ?~ "flow"
1391+instance HasSwaggerAesonOptions Operation where
1392+ swaggerAesonOptions _ = mkSwaggerAesonOptions "operation"
1393+instance HasSwaggerAesonOptions Param where
1394+ swaggerAesonOptions _ = mkSwaggerAesonOptions "param" & saoSubObject ?~ "schema"
1395+instance HasSwaggerAesonOptions ParamOtherSchema where
1396+ swaggerAesonOptions _ = mkSwaggerAesonOptions "paramOtherSchema" & saoSubObject ?~ "paramSchema"
1397+instance HasSwaggerAesonOptions PathItem where
1398+ swaggerAesonOptions _ = mkSwaggerAesonOptions "pathItem"
1399+instance HasSwaggerAesonOptions Response where
1400+ swaggerAesonOptions _ = mkSwaggerAesonOptions "response"
1401+instance HasSwaggerAesonOptions Responses where
1402+ swaggerAesonOptions _ = mkSwaggerAesonOptions "responses" & saoSubObject ?~ "responses"
1403+instance HasSwaggerAesonOptions SecurityScheme where
1404+ swaggerAesonOptions _ = mkSwaggerAesonOptions "securityScheme" & saoSubObject ?~ "type"
1405+instance HasSwaggerAesonOptions Schema where
1406+ swaggerAesonOptions _ = mkSwaggerAesonOptions "schema" & saoSubObject ?~ "paramSchema"
1407+instance HasSwaggerAesonOptions Swagger where
1408+ swaggerAesonOptions _ = mkSwaggerAesonOptions "swagger" & saoAdditionalPairs .~ [("swagger", "2.0")]
1409+
1410+instance HasSwaggerAesonOptions (ParamSchema ('SwaggerKindNormal t)) where
1411+ swaggerAesonOptions _ = mkSwaggerAesonOptions "paramSchema" & saoSubObject ?~ "items"
1412+instance HasSwaggerAesonOptions (ParamSchema 'SwaggerKindParamOtherSchema) where
1413+ swaggerAesonOptions _ = mkSwaggerAesonOptions "paramSchema" & saoSubObject ?~ "items"
1414+-- NOTE: Schema doesn't have 'items' sub object!
1415+instance HasSwaggerAesonOptions (ParamSchema 'SwaggerKindSchema) where
1416+ swaggerAesonOptions _ = mkSwaggerAesonOptions "paramSchema"
1417+
1418+instance AesonDefaultValue (ParamSchema s)
1419+instance AesonDefaultValue OAuth2Flow
1420+instance AesonDefaultValue Responses
1421+instance AesonDefaultValue ParamAnySchema
1422+instance AesonDefaultValue SecuritySchemeType
1423+instance AesonDefaultValue (SwaggerType a)
1424+instance AesonDefaultValue MimeList where defaultValue = Just mempty
1425+instance AesonDefaultValue Info
1426+instance AesonDefaultValue ParamLocation
1427+instance AesonDefaultValue SecurityDefinitions where defaultValue = Just $ SecurityDefinitions mempty
src/Data/Swagger/Internal/AesonUtils.hsnew file+346
@@ -0,0 +1,346 @@
1+{-# LANGUAGE CPP #-}
2+{-# LANGUAGE DataKinds #-}
3+{-# LANGUAGE FlexibleContexts #-}
4+{-# LANGUAGE GADTs #-}
5+{-# LANGUAGE ScopedTypeVariables #-}
6+{-# LANGUAGE ExplicitForAll #-}
7+{-# LANGUAGE TemplateHaskell #-}
8+#if __GLASGOW_HASKELL__ >= 800
9+{-# LANGUAGE UndecidableSuperClasses #-}
10+#endif
11+module Data.Swagger.Internal.AesonUtils (
12+ -- * Generic functions
13+ AesonDefaultValue(..),
14+ sopSwaggerGenericToJSON,
15+#if MIN_VERSION_aeson(0,10,0)
16+ sopSwaggerGenericToEncoding,
17+#endif
18+ sopSwaggerGenericToJSONWithOpts,
19+ sopSwaggerGenericParseJSON,
20+ -- * Options
21+ HasSwaggerAesonOptions(..),
22+ SwaggerAesonOptions,
23+ mkSwaggerAesonOptions,
24+ saoPrefix,
25+ saoAdditionalPairs,
26+ saoSubObject,
27+ ) where
28+
29+import Prelude ()
30+import Prelude.Compat
31+
32+import Control.Applicative ((<|>))
33+import Control.Lens (makeLenses, (^.))
34+import Control.Monad (unless)
35+import Data.Aeson (ToJSON(..), FromJSON(..), Value(..), Object, object, (.:), (.:?), (.!=), withObject)
36+import Data.Aeson.Types (Parser, Pair)
37+import Data.Char (toLower, isUpper)
38+import Data.Foldable (traverse_)
39+import Data.Text (Text)
40+
41+import Generics.SOP
42+
43+import qualified Data.Text as T
44+import qualified Data.HashMap.Strict as HM
45+import qualified Data.Set as Set
46+import qualified Data.HashMap.Strict.InsOrd as InsOrd
47+import qualified Data.HashSet.InsOrd as InsOrdHS
48+
49+#if MIN_VERSION_aeson(0,10,0)
50+import Data.Aeson (Encoding, pairs, (.=), Series)
51+#endif
52+
53+-------------------------------------------------------------------------------
54+-- SwaggerAesonOptions
55+-------------------------------------------------------------------------------
56+
57+data SwaggerAesonOptions = SwaggerAesonOptions
58+ { _saoPrefix :: String
59+ , _saoAdditionalPairs :: [(Text, Value)]
60+ , _saoSubObject :: Maybe String
61+ }
62+
63+mkSwaggerAesonOptions
64+ :: String -- ^ prefix
65+ -> SwaggerAesonOptions
66+mkSwaggerAesonOptions pfx = SwaggerAesonOptions pfx [] Nothing
67+
68+makeLenses ''SwaggerAesonOptions
69+
70+class (Generic a, All2 AesonDefaultValue (Code a)) => HasSwaggerAesonOptions a where
71+ swaggerAesonOptions :: Proxy a -> SwaggerAesonOptions
72+
73+ -- So far we use only default definitions
74+ aesonDefaults :: Proxy a -> POP Maybe (Code a)
75+ aesonDefaults _ = hcpure (Proxy :: Proxy AesonDefaultValue) defaultValue
76+
77+-------------------------------------------------------------------------------
78+-- Generics
79+-------------------------------------------------------------------------------
80+
81+class AesonDefaultValue a where
82+ defaultValue :: Maybe a
83+ defaultValue = Nothing
84+
85+instance AesonDefaultValue Text where defaultValue = Nothing
86+instance AesonDefaultValue (Maybe a) where defaultValue = Just Nothing
87+instance AesonDefaultValue [a] where defaultValue = Just []
88+instance AesonDefaultValue (Set.Set a) where defaultValue = Just Set.empty
89+instance AesonDefaultValue (InsOrdHS.InsOrdHashSet k) where defaultValue = Just InsOrdHS.empty
90+instance AesonDefaultValue (InsOrd.InsOrdHashMap k v) where defaultValue = Just InsOrd.empty
91+
92+-------------------------------------------------------------------------------
93+-- ToJSON
94+-------------------------------------------------------------------------------
95+
96+-- | Generic serialisation for swagger records.
97+--
98+-- Features
99+--
100+-- * omits nulls, empty objects and empty arrays (configurable)
101+-- * possible to add fields
102+-- * possible to merge sub-object
103+sopSwaggerGenericToJSON
104+ :: forall a xs.
105+ ( HasDatatypeInfo a
106+ , HasSwaggerAesonOptions a
107+ , All2 ToJSON (Code a)
108+ , All2 Eq (Code a)
109+ , Code a ~ '[xs]
110+ )
111+ => a
112+ -> Value
113+sopSwaggerGenericToJSON x =
114+ let ps = sopSwaggerGenericToJSON' opts (from x) (datatypeInfo proxy) (aesonDefaults proxy)
115+ in object (opts ^. saoAdditionalPairs ++ ps)
116+ where
117+ proxy = Proxy :: Proxy a
118+ opts = swaggerAesonOptions proxy
119+
120+-- | *TODO:* This is only used by ToJSON (ParamSchema SwaggerKindSchema)
121+--
122+-- Also uses default `aesonDefaults`
123+sopSwaggerGenericToJSONWithOpts
124+ :: forall a xs.
125+ ( Generic a
126+ , All2 AesonDefaultValue (Code a)
127+ , HasDatatypeInfo a
128+ , All2 ToJSON (Code a)
129+ , All2 Eq (Code a)
130+ , Code a ~ '[xs]
131+ )
132+ => SwaggerAesonOptions
133+ -> a
134+ -> Value
135+sopSwaggerGenericToJSONWithOpts opts x =
136+ let ps = sopSwaggerGenericToJSON' opts (from x) (datatypeInfo proxy) defs
137+ in object (opts ^. saoAdditionalPairs ++ ps)
138+ where
139+ proxy = Proxy :: Proxy a
140+ defs = hcpure (Proxy :: Proxy AesonDefaultValue) defaultValue
141+
142+sopSwaggerGenericToJSON'
143+ :: (All2 ToJSON '[xs], All2 Eq '[xs])
144+ => SwaggerAesonOptions
145+ -> SOP I '[xs]
146+ -> DatatypeInfo '[xs]
147+ -> POP Maybe '[xs]
148+ -> [Pair]
149+#if MIN_VERSION_generics_sop(0,5,0)
150+sopSwaggerGenericToJSON' opts (SOP (Z fields)) (ADT _ _ (Record _ fieldsInfo :* Nil) _) (POP (defs :* Nil)) =
151+#else
152+sopSwaggerGenericToJSON' opts (SOP (Z fields)) (ADT _ _ (Record _ fieldsInfo :* Nil)) (POP (defs :* Nil)) =
153+#endif
154+ sopSwaggerGenericToJSON'' opts fields fieldsInfo defs
155+sopSwaggerGenericToJSON' _ _ _ _ = error "sopSwaggerGenericToJSON: unsupported type"
156+
157+sopSwaggerGenericToJSON''
158+ :: (All ToJSON xs, All Eq xs)
159+ => SwaggerAesonOptions
160+ -> NP I xs
161+ -> NP FieldInfo xs
162+ -> NP Maybe xs
163+ -> [Pair]
164+sopSwaggerGenericToJSON'' (SwaggerAesonOptions prefix _ sub) = go
165+ where
166+ go :: (All ToJSON ys, All Eq ys) => NP I ys -> NP FieldInfo ys -> NP Maybe ys -> [Pair]
167+ go Nil Nil Nil = []
168+ go (I x :* xs) (FieldInfo name :* names) (def :* defs)
169+ | Just name' == sub = case json of
170+ Object m -> HM.toList m ++ rest
171+ Null -> rest
172+ _ -> error $ "sopSwaggerGenericToJSON: subjson is not an object: " ++ show json
173+ -- If default value: omit it.
174+ | Just x == def =
175+ rest
176+ | otherwise =
177+ (T.pack name', json) : rest
178+ where
179+ json = toJSON x
180+ name' = fieldNameModifier name
181+ rest = go xs names defs
182+#if __GLASGOW_HASKELL__ < 800
183+ go _ _ _ = error "not empty"
184+#endif
185+
186+ fieldNameModifier = modifier . drop 1
187+ modifier = lowerFirstUppers . drop (length prefix)
188+ lowerFirstUppers s = map toLower x ++ y
189+ where (x, y) = span isUpper s
190+
191+-------------------------------------------------------------------------------
192+-- FromJSON
193+-------------------------------------------------------------------------------
194+
195+sopSwaggerGenericParseJSON
196+ :: forall a xs.
197+ ( HasDatatypeInfo a
198+ , HasSwaggerAesonOptions a
199+ , All2 FromJSON (Code a)
200+ , All2 Eq (Code a)
201+ , Code a ~ '[xs]
202+ )
203+ => Value
204+ -> Parser a
205+sopSwaggerGenericParseJSON = withObject "Swagger Record Object" $ \obj ->
206+ let ps = sopSwaggerGenericParseJSON' opts obj (datatypeInfo proxy) (aesonDefaults proxy)
207+ in do
208+ traverse_ (parseAdditionalField obj) (opts ^. saoAdditionalPairs)
209+ to <$> ps
210+ where
211+ proxy = Proxy :: Proxy a
212+ opts = swaggerAesonOptions proxy
213+
214+ parseAdditionalField :: Object -> (Text, Value) -> Parser ()
215+ parseAdditionalField obj (k, v) = do
216+ v' <- obj .: k
217+ unless (v == v') $ fail $
218+ "Additonal field don't match for key " ++ T.unpack k
219+ ++ ": " ++ show v
220+ ++ " /= " ++ show v'
221+
222+sopSwaggerGenericParseJSON'
223+ :: (All2 FromJSON '[xs], All2 Eq '[xs])
224+ => SwaggerAesonOptions
225+ -> Object
226+ -> DatatypeInfo '[xs]
227+ -> POP Maybe '[xs]
228+ -> Parser (SOP I '[xs])
229+#if MIN_VERSION_generics_sop(0,5,0)
230+sopSwaggerGenericParseJSON' opts obj (ADT _ _ (Record _ fieldsInfo :* Nil) _) (POP (defs :* Nil)) =
231+#else
232+sopSwaggerGenericParseJSON' opts obj (ADT _ _ (Record _ fieldsInfo :* Nil)) (POP (defs :* Nil)) =
233+#endif
234+ SOP . Z <$> sopSwaggerGenericParseJSON'' opts obj fieldsInfo defs
235+sopSwaggerGenericParseJSON' _ _ _ _ = error "sopSwaggerGenericParseJSON: unsupported type"
236+
237+sopSwaggerGenericParseJSON''
238+ :: (All FromJSON xs, All Eq xs)
239+ => SwaggerAesonOptions
240+ -> Object
241+ -> NP FieldInfo xs
242+ -> NP Maybe xs
243+ -> Parser (NP I xs)
244+sopSwaggerGenericParseJSON'' (SwaggerAesonOptions prefix _ sub) obj = go
245+ where
246+ go :: (All FromJSON ys, All Eq ys) => NP FieldInfo ys -> NP Maybe ys -> Parser (NP I ys)
247+ go Nil Nil = pure Nil
248+ go (FieldInfo name :* names) (def :* defs)
249+ | Just name' == sub =
250+ -- Note: we might strip fields of outer structure.
251+ cons <$> (withDef $ parseJSON $ Object obj) <*> rest
252+ | otherwise = case def of
253+ Just def' -> cons <$> obj .:? T.pack name' .!= def' <*> rest
254+ Nothing -> cons <$> obj .: T.pack name' <*> rest
255+ where
256+ cons h t = I h :* t
257+ name' = fieldNameModifier name
258+ rest = go names defs
259+
260+ withDef = case def of
261+ Just def' -> (<|> pure def')
262+ Nothing -> id
263+#if __GLASGOW_HASKELL__ < 800
264+ go _ _ = error "not empty"
265+#endif
266+
267+ fieldNameModifier = modifier . drop 1
268+ modifier = lowerFirstUppers . drop (length prefix)
269+ lowerFirstUppers s = map toLower x ++ y
270+ where (x, y) = span isUpper s
271+
272+-------------------------------------------------------------------------------
273+-- ToEncoding
274+-------------------------------------------------------------------------------
275+
276+#if MIN_VERSION_aeson(0,10,0)
277+
278+sopSwaggerGenericToEncoding
279+ :: forall a xs.
280+ ( HasDatatypeInfo a
281+ , HasSwaggerAesonOptions a
282+ , All2 ToJSON (Code a)
283+ , All2 Eq (Code a)
284+ , Code a ~ '[xs]
285+ )
286+ => a
287+ -> Encoding
288+sopSwaggerGenericToEncoding x =
289+ let ps = sopSwaggerGenericToEncoding' opts (from x) (datatypeInfo proxy) (aesonDefaults proxy)
290+ in pairs (pairsToSeries (opts ^. saoAdditionalPairs) <> ps)
291+ where
292+ proxy = Proxy :: Proxy a
293+ opts = swaggerAesonOptions proxy
294+
295+pairsToSeries :: [Pair] -> Series
296+pairsToSeries = foldMap (\(k, v) -> (k .= v))
297+
298+sopSwaggerGenericToEncoding'
299+ :: (All2 ToJSON '[xs], All2 Eq '[xs])
300+ => SwaggerAesonOptions
301+ -> SOP I '[xs]
302+ -> DatatypeInfo '[xs]
303+ -> POP Maybe '[xs]
304+ -> Series
305+#if MIN_VERSION_generics_sop(0,5,0)
306+sopSwaggerGenericToEncoding' opts (SOP (Z fields)) (ADT _ _ (Record _ fieldsInfo :* Nil) _) (POP (defs :* Nil)) =
307+#else
308+sopSwaggerGenericToEncoding' opts (SOP (Z fields)) (ADT _ _ (Record _ fieldsInfo :* Nil)) (POP (defs :* Nil)) =
309+#endif
310+ sopSwaggerGenericToEncoding'' opts fields fieldsInfo defs
311+sopSwaggerGenericToEncoding' _ _ _ _ = error "sopSwaggerGenericToEncoding: unsupported type"
312+
313+sopSwaggerGenericToEncoding''
314+ :: (All ToJSON xs, All Eq xs)
315+ => SwaggerAesonOptions
316+ -> NP I xs
317+ -> NP FieldInfo xs
318+ -> NP Maybe xs
319+ -> Series
320+sopSwaggerGenericToEncoding'' (SwaggerAesonOptions prefix _ sub) = go
321+ where
322+ go :: (All ToJSON ys, All Eq ys) => NP I ys -> NP FieldInfo ys -> NP Maybe ys -> Series
323+ go Nil Nil Nil = mempty
324+ go (I x :* xs) (FieldInfo name :* names) (def :* defs)
325+ | Just name' == sub = case toJSON x of
326+ Object m -> pairsToSeries (HM.toList m) <> rest
327+ Null -> rest
328+ _ -> error $ "sopSwaggerGenericToJSON: subjson is not an object: " ++ show (toJSON x)
329+ -- If default value: omit it.
330+ | Just x == def =
331+ rest
332+ | otherwise =
333+ (T.pack name' .= x) <> rest
334+ where
335+ name' = fieldNameModifier name
336+ rest = go xs names defs
337+#if __GLASGOW_HASKELL__ < 800
338+ go _ _ _ = error "not empty"
339+#endif
340+
341+ fieldNameModifier = modifier . drop 1
342+ modifier = lowerFirstUppers . drop (length prefix)
343+ lowerFirstUppers s = map toLower x ++ y
344+ where (x, y) = span isUpper s
345+
346+#endif
src/Data/Swagger/Internal/ParamSchema.hs+120−23
@@ -1,4 +1,5 @@
11{-# LANGUAGE CPP #-}
2+{-# LANGUAGE DataKinds #-}
23{-# LANGUAGE DefaultSignatures #-}
34{-# LANGUAGE FlexibleContexts #-}
45{-# LANGUAGE FlexibleInstances #-}
@@ -7,13 +8,21 @@
78{-# LANGUAGE PackageImports #-}
89{-# LANGUAGE PolyKinds #-}
910{-# LANGUAGE ScopedTypeVariables #-}
11+{-# LANGUAGE TypeFamilies #-}
1012{-# LANGUAGE TypeOperators #-}
1113{-# LANGUAGE TypeSynonymInstances #-}
14+{-# LANGUAGE UndecidableInstances #-}
15+#if __GLASGOW_HASKELL__ >= 800
16+-- Generic a is redundant in ToParamSchema a default imple
17+{-# OPTIONS_GHC -Wno-redundant-constraints #-}
18+-- For TypeErrors
19+{-# OPTIONS_GHC -Wno-unticked-promoted-constructors #-}
20+#endif
1221#include "overlapping-compat.h"
1322module Data.Swagger.Internal.ParamSchema where
1423
1524import Control.Lens
16−import Data.Aeson
25+import Data.Aeson (ToJSON (..))
1726import Data.Proxy
1827import GHC.Generics
1928
@@ -22,15 +31,50 @@ import "unordered-containers" Data.HashSet (HashSet)
2231import Data.Monoid
2332import Data.Set (Set)
2433import Data.Scientific
34+import Data.Fixed (HasResolution(..), Fixed, Pico)
2535import qualified Data.Text as T
2636import qualified Data.Text.Lazy as TL
2737import Data.Time
38+import qualified Data.Vector as V
39+import qualified Data.Vector.Primitive as VP
40+import qualified Data.Vector.Storable as VS
41+import qualified Data.Vector.Unboxed as VU
42+import Data.Version (Version)
43+import Numeric.Natural.Compat (Natural)
2844import Data.Word
45+import Data.UUID.Types (UUID)
46+import Web.Cookie (SetCookie)
2947
3048import Data.Swagger.Internal
3149import Data.Swagger.Lens
3250import Data.Swagger.SchemaOptions
3351
52+#if __GLASGOW_HASKELL__ < 800
53+#else
54+import qualified Data.ByteString as BS
55+import qualified Data.ByteString.Lazy as BSL
56+import GHC.TypeLits (TypeError, ErrorMessage(..))
57+#endif
58+
59+-- | Default schema for binary data (any sequence of octets).
60+binaryParamSchema :: ParamSchema t
61+binaryParamSchema = mempty
62+ & type_ ?~ SwaggerString
63+ & format ?~ "binary"
64+
65+-- | Default schema for binary data (base64 encoded).
66+byteParamSchema :: ParamSchema t
67+byteParamSchema = mempty
68+ & type_ ?~ SwaggerString
69+ & format ?~ "byte"
70+
71+-- | Default schema for password string.
72+-- @"password"@ format is used to hint UIs the input needs to be obscured.
73+passwordParamSchema :: ParamSchema t
74+passwordParamSchema = mempty
75+ & type_ ?~ SwaggerString
76+ & format ?~ "password"
77+
3478-- | Convert a type into a plain @'ParamSchema'@.
3579--
3680-- An example type and instance:
@@ -43,9 +87,9 @@ import Data.Swagger.SchemaOptions
4387-- data Direction = Up | Down
4488--
4589-- instance ToParamSchema Direction where
46−-- toParamSchema = mempty
47−-- & type_ .~ SwaggerString
48−-- & enum_ .~ [ \"Up\", \"Down\" ]
90+-- toParamSchema _ = mempty
91+-- & type_ ?~ SwaggerString
92+-- & enum_ ?~ [ \"Up\", \"Down\" ]
4993-- @
5094--
5195-- Instead of manually writing your @'ToParamSchema'@ instance you can
@@ -71,18 +115,24 @@ class ToParamSchema a where
71115 --
72116 -- >>> encode $ toParamSchema (Proxy :: Proxy Integer)
73117 -- "{\"type\":\"integer\"}"
74− toParamSchema :: proxy a -> ParamSchema t
75− default toParamSchema :: (Generic a, GToParamSchema (Rep a)) => proxy a -> ParamSchema t
118+ toParamSchema :: Proxy a -> ParamSchema t
119+ default toParamSchema :: (Generic a, GToParamSchema (Rep a)) => Proxy a -> ParamSchema t
76120 toParamSchema = genericToParamSchema defaultSchemaOptions
77121
78122instance OVERLAPPING_ ToParamSchema String where
79− toParamSchema _ = mempty & type_ .~ SwaggerString
123+ toParamSchema _ = mempty & type_ ?~ SwaggerString
80124
81125instance ToParamSchema Bool where
82− toParamSchema _ = mempty & type_ .~ SwaggerBoolean
126+ toParamSchema _ = mempty & type_ ?~ SwaggerBoolean
83127
84128instance ToParamSchema Integer where
85− toParamSchema _ = mempty & type_ .~ SwaggerInteger
129+ toParamSchema _ = mempty & type_ ?~ SwaggerInteger
130+
131+instance ToParamSchema Natural where
132+ toParamSchema _ = mempty
133+ & type_ ?~ SwaggerInteger
134+ & minimum_ ?~ 0
135+ & exclusiveMinimum ?~ False
86136
87137instance ToParamSchema Int where toParamSchema = toParamSchemaBoundedIntegral
88138instance ToParamSchema Int8 where toParamSchema = toParamSchemaBoundedIntegral
@@ -104,40 +154,51 @@ instance ToParamSchema Word64 where toParamSchema = toParamSchemaBoundedIntegral
104154--
105155-- >>> encode $ toParamSchemaBoundedIntegral (Proxy :: Proxy Int8)
106156-- "{\"maximum\":127,\"minimum\":-128,\"type\":\"integer\"}"
107−toParamSchemaBoundedIntegral :: forall proxy a t. (Bounded a, Integral a) => proxy a -> ParamSchema t
157+toParamSchemaBoundedIntegral :: forall a t. (Bounded a, Integral a) => Proxy a -> ParamSchema t
108158toParamSchemaBoundedIntegral _ = mempty
109− & type_ .~ SwaggerInteger
159+ & type_ ?~ SwaggerInteger
110160 & minimum_ ?~ fromInteger (toInteger (minBound :: a))
111161 & maximum_ ?~ fromInteger (toInteger (maxBound :: a))
112162
113163instance ToParamSchema Char where
114164 toParamSchema _ = mempty
115− & type_ .~ SwaggerString
165+ & type_ ?~ SwaggerString
116166 & maxLength ?~ 1
117167 & minLength ?~ 1
118168
119169instance ToParamSchema Scientific where
120− toParamSchema _ = mempty & type_ .~ SwaggerNumber
170+ toParamSchema _ = mempty & type_ ?~ SwaggerNumber
171+
172+instance HasResolution a => ToParamSchema (Fixed a) where
173+ toParamSchema _ = mempty
174+ & type_ ?~ SwaggerNumber
175+ & multipleOf ?~ (recip . fromInteger $ resolution (Proxy :: Proxy a))
121176
122177instance ToParamSchema Double where
123178 toParamSchema _ = mempty
124− & type_ .~ SwaggerNumber
179+ & type_ ?~ SwaggerNumber
125180 & format ?~ "double"
126181
127182instance ToParamSchema Float where
128183 toParamSchema _ = mempty
129− & type_ .~ SwaggerNumber
184+ & type_ ?~ SwaggerNumber
130185 & format ?~ "float"
131186
132187timeParamSchema :: String -> ParamSchema t
133188timeParamSchema fmt = mempty
134− & type_ .~ SwaggerString
189+ & type_ ?~ SwaggerString
135190 & format ?~ T.pack fmt
136191
137192-- | Format @"date"@ corresponds to @yyyy-mm-dd@ format.
138193instance ToParamSchema Day where
139194 toParamSchema _ = timeParamSchema "date"
140195
196+-- |
197+-- >>> toParamSchema (Proxy :: Proxy TimeOfDay) ^. format
198+-- Just "hh:MM:ss"
199+instance ToParamSchema TimeOfDay where
200+ toParamSchema _ = timeParamSchema "hh:MM:ss"
201+
141202-- |
142203-- >>> toParamSchema (Proxy :: Proxy LocalTime) ^. format
143204-- Just "yyyy-mm-ddThh:MM:ss"
@@ -157,7 +218,7 @@ instance ToParamSchema UTCTime where
157218 toParamSchema _ = timeParamSchema "yyyy-mm-ddThh:MM:ssZ"
158219
159220instance ToParamSchema NominalDiffTime where
160− toParamSchema _ = toParamSchema (Proxy :: Proxy Integer)
221+ toParamSchema _ = toParamSchema (Proxy :: Proxy Pico)
161222
162223instance ToParamSchema T.Text where
163224 toParamSchema _ = toParamSchema (Proxy :: Proxy String)
@@ -165,6 +226,28 @@ instance ToParamSchema T.Text where
165226instance ToParamSchema TL.Text where
166227 toParamSchema _ = toParamSchema (Proxy :: Proxy String)
167228
229+instance ToParamSchema Version where
230+ toParamSchema _ = mempty
231+ & type_ ?~ SwaggerString
232+ & pattern ?~ "^\\d+(\\.\\d+)*$"
233+
234+instance ToParamSchema SetCookie where
235+ toParamSchema _ = mempty
236+ & type_ ?~ SwaggerString
237+
238+
239+#if __GLASGOW_HASKELL__ < 800
240+#else
241+type family ToParamSchemaByteStringError bs where
242+ ToParamSchemaByteStringError bs = TypeError
243+ ( 'Text "Impossible to have an instance " :<>: ShowType (ToParamSchema bs) :<>: Text "."
244+ :$$: 'Text "Please, use a newtype wrapper around " :<>: ShowType bs :<>: Text " instead."
245+ :$$: 'Text "Consider using byteParamSchema or binaryParamSchema templates." )
246+
247+instance ToParamSchemaByteStringError BS.ByteString => ToParamSchema BS.ByteString where toParamSchema = error "impossible"
248+instance ToParamSchemaByteStringError BSL.ByteString => ToParamSchema BSL.ByteString where toParamSchema = error "impossible"
249+#endif
250+
168251instance ToParamSchema All where toParamSchema _ = toParamSchema (Proxy :: Proxy Bool)
169252instance ToParamSchema Any where toParamSchema _ = toParamSchema (Proxy :: Proxy Bool)
170253instance ToParamSchema a => ToParamSchema (Sum a) where toParamSchema _ = toParamSchema (Proxy :: Proxy a)
@@ -173,11 +256,18 @@ instance ToParamSchema a => ToParamSchema (First a) where toParamSchema _ = to
173256instance ToParamSchema a => ToParamSchema (Last a) where toParamSchema _ = toParamSchema (Proxy :: Proxy a)
174257instance ToParamSchema a => ToParamSchema (Dual a) where toParamSchema _ = toParamSchema (Proxy :: Proxy a)
175258
259+instance ToParamSchema a => ToParamSchema (Identity a) where toParamSchema _ = toParamSchema (Proxy :: Proxy a)
260+
176261instance ToParamSchema a => ToParamSchema [a] where
177262 toParamSchema _ = mempty
178− & type_ .~ SwaggerArray
263+ & type_ ?~ SwaggerArray
179264 & items ?~ SwaggerItemsPrimitive Nothing (toParamSchema (Proxy :: Proxy a))
180265
266+instance ToParamSchema a => ToParamSchema (V.Vector a) where toParamSchema _ = toParamSchema (Proxy :: Proxy [a])
267+instance ToParamSchema a => ToParamSchema (VP.Vector a) where toParamSchema _ = toParamSchema (Proxy :: Proxy [a])
268+instance ToParamSchema a => ToParamSchema (VS.Vector a) where toParamSchema _ = toParamSchema (Proxy :: Proxy [a])
269+instance ToParamSchema a => ToParamSchema (VU.Vector a) where toParamSchema _ = toParamSchema (Proxy :: Proxy [a])
270+
181271instance ToParamSchema a => ToParamSchema (Set a) where
182272 toParamSchema _ = toParamSchema (Proxy :: Proxy [a])
183273 & uniqueItems ?~ True
@@ -190,20 +280,25 @@ instance ToParamSchema a => ToParamSchema (HashSet a) where
190280-- "{\"type\":\"string\",\"enum\":[\"_\"]}"
191281instance ToParamSchema () where
192282 toParamSchema _ = mempty
193− & type_ .~ SwaggerString
283+ & type_ ?~ SwaggerString
194284 & enum_ ?~ ["_"]
195285
286+instance ToParamSchema UUID where
287+ toParamSchema _ = mempty
288+ & type_ ?~ SwaggerString
289+ & format ?~ "uuid"
290+
196291-- | A configurable generic @'ParamSchema'@ creator.
197292--
198293-- >>> :set -XDeriveGeneric
199294-- >>> data Color = Red | Blue deriving Generic
200295-- >>> encode $ genericToParamSchema defaultSchemaOptions (Proxy :: Proxy Color)
201296-- "{\"type\":\"string\",\"enum\":[\"Red\",\"Blue\"]}"
202−genericToParamSchema :: forall proxy a t. (Generic a, GToParamSchema (Rep a)) => SchemaOptions -> proxy a -> ParamSchema t
297+genericToParamSchema :: forall a t. (Generic a, GToParamSchema (Rep a)) => SchemaOptions -> Proxy a -> ParamSchema t
203298genericToParamSchema opts _ = gtoParamSchema opts (Proxy :: Proxy (Rep a)) mempty
204299
205300class GToParamSchema (f :: * -> *) where
206− gtoParamSchema :: SchemaOptions -> proxy f -> ParamSchema t -> ParamSchema t
301+ gtoParamSchema :: SchemaOptions -> Proxy f -> ParamSchema t -> ParamSchema t
207302
208303instance GToParamSchema f => GToParamSchema (D1 d f) where
209304 gtoParamSchema opts _ = gtoParamSchema opts (Proxy :: Proxy f)
@@ -221,14 +316,14 @@ instance (GEnumParamSchema f, GEnumParamSchema g) => GToParamSchema (f :+: g) wh
221316 gtoParamSchema opts _ = genumParamSchema opts (Proxy :: Proxy (f :+: g))
222317
223318class GEnumParamSchema (f :: * -> *) where
224− genumParamSchema :: SchemaOptions -> proxy f -> ParamSchema t -> ParamSchema t
319+ genumParamSchema :: SchemaOptions -> Proxy f -> ParamSchema t -> ParamSchema t
225320
226321instance (GEnumParamSchema f, GEnumParamSchema g) => GEnumParamSchema (f :+: g) where
227322 genumParamSchema opts _ = genumParamSchema opts (Proxy :: Proxy f) . genumParamSchema opts (Proxy :: Proxy g)
228323
229324instance Constructor c => GEnumParamSchema (C1 c U1) where
230325 genumParamSchema opts _ s = s
231− & type_ .~ SwaggerString
326+ & type_ ?~ SwaggerString
232327 & enum_ %~ addEnumValue tag
233328 where
234329 tag = toJSON (constructorTagModifier opts (conName (Proxy3 :: Proxy3 c f p)))
@@ -238,3 +333,5 @@ instance Constructor c => GEnumParamSchema (C1 c U1) where
238333
239334data Proxy3 a b c = Proxy3
240335
336+-- $setup
337+-- >>> import Data.Aeson (encode)
src/Data/Swagger/Internal/Schema.hs+386−81
@@ -1,8 +1,10 @@
11{-# LANGUAGE CPP #-}
2+{-# LANGUAGE ConstraintKinds #-}
23{-# LANGUAGE DefaultSignatures #-}
34{-# LANGUAGE FlexibleContexts #-}
45{-# LANGUAGE FlexibleInstances #-}
56{-# LANGUAGE KindSignatures #-}
7+{-# LANGUAGE DataKinds #-}
68{-# LANGUAGE OverloadedLists #-}
79{-# LANGUAGE OverloadedStrings #-}
810{-# LANGUAGE PackageImports #-}
@@ -12,6 +14,13 @@
1214{-# LANGUAGE TypeFamilies #-}
1315{-# LANGUAGE TypeOperators #-}
1416{-# LANGUAGE TypeSynonymInstances #-}
17+{-# LANGUAGE UndecidableInstances #-}
18+#if __GLASGOW_HASKELL__ >= 800
19+-- Few generics related redundant constraints
20+{-# OPTIONS_GHC -Wno-redundant-constraints #-}
21+-- For TypeErrors
22+{-# OPTIONS_GHC -Wno-unticked-promoted-constructors #-}
23+#endif
1524#include "overlapping-compat.h"
1625module Data.Swagger.Internal.Schema where
1726
@@ -23,34 +32,50 @@ import Data.Data.Lens (template)
2332
2433import Control.Monad
2534import Control.Monad.Writer
26−import Data.Aeson
35+import Data.Aeson (ToJSON (..), ToJSONKey (..), ToJSONKeyFunction (..), Value (..), Object(..))
2736import Data.Char
2837import Data.Data (Data)
2938import Data.Foldable (traverse_)
3039import Data.HashMap.Strict (HashMap)
3140import qualified Data.HashMap.Strict as HashMap
32−import "unordered-containers" Data.HashSet (HashSet)
41+import "unordered-containers" Data.HashSet (HashSet)
42+import qualified "unordered-containers" Data.HashSet as HashSet
43+import qualified Data.HashMap.Strict.InsOrd as InsOrdHashMap
3344import Data.Int
3445import Data.IntSet (IntSet)
3546import Data.IntMap (IntMap)
47+import Data.List.NonEmpty.Compat (NonEmpty)
3648import Data.Map (Map)
3749import Data.Proxy
3850import Data.Scientific (Scientific)
51+import Data.Fixed (Fixed, HasResolution, Pico)
3952import Data.Set (Set)
4053import qualified Data.Text as T
4154import qualified Data.Text.Lazy as TL
4255import Data.Time
56+import qualified Data.Vector as V
57+import qualified Data.Vector.Primitive as VP
58+import qualified Data.Vector.Storable as VS
59+import qualified Data.Vector.Unboxed as VU
60+import Data.Version (Version)
61+import Numeric.Natural.Compat (Natural)
4362import Data.Word
4463import GHC.Generics
64+import qualified Data.UUID.Types as UUID
4565
4666import Data.Swagger.Declare
4767import Data.Swagger.Internal
4868import Data.Swagger.Internal.ParamSchema (ToParamSchema(..))
4969import Data.Swagger.Lens hiding (name, schema)
70+import qualified Data.Swagger.Lens as Swagger
5071import Data.Swagger.SchemaOptions
72+import Data.Swagger.Internal.TypeShape
5173
52−#ifdef __DOCTEST__
53−import Data.Swagger.Lens (name, schema)
74+#if __GLASGOW_HASKELL__ < 800
75+#else
76+import qualified Data.ByteString as BS
77+import qualified Data.ByteString.Lazy as BSL
78+import GHC.TypeLits (TypeError, ErrorMessage(..))
5479#endif
5580
5681unnamed :: Schema -> NamedSchema
@@ -77,19 +102,21 @@ rename name (NamedSchema _ schema) = NamedSchema name schema
77102-- {-\# LANGUAGE OverloadedLists \#-} -- allows to write 'Map' and 'HashMap' as lists
78103--
79104-- import Control.Lens
105+-- import Data.Proxy
106+-- import Data.Swagger
80107--
81108-- data Coord = Coord { x :: Double, y :: Double }
82109--
83110-- instance ToSchema Coord where
84−-- declareNamedSchema = pure (Just \"Coord\", schema)
85−-- where
86−-- schema = mempty
87−-- & type_ .~ SwaggerObject
88−-- & properties .~
89−-- [ (\"x\", toSchemaRef (Proxy :: Proxy Double))
90−-- , (\"y\", toSchemaRef (Proxy :: Proxy Double))
91−-- ]
92−-- & required .~ [ \"x\", \"y\" ]
111+-- declareNamedSchema _ = do
112+-- doubleSchema <- declareSchemaRef (Proxy :: Proxy Double)
113+-- return $ NamedSchema (Just \"Coord\") $ mempty
114+-- & type_ ?~ SwaggerObject
115+-- & properties .~
116+-- [ (\"x\", doubleSchema)
117+-- , (\"y\", doubleSchema)
118+-- ]
119+-- & required .~ [ \"x\", \"y\" ]
93120-- @
94121--
95122-- Instead of manually writing your @'ToSchema'@ instance you can
@@ -115,12 +142,17 @@ class ToSchema a where
115142 -- together with all used definitions.
116143 -- Note that the schema itself is included in definitions
117144 -- only if it is recursive (and thus needs its definition in scope).
118− declareNamedSchema :: proxy a -> Declare (Definitions Schema) NamedSchema
119− default declareNamedSchema :: (Generic a, GToSchema (Rep a)) => proxy a -> Declare (Definitions Schema) NamedSchema
145+ declareNamedSchema :: Proxy a -> Declare (Definitions Schema) NamedSchema
146+ default declareNamedSchema :: (Generic a, GToSchema (Rep a), TypeHasSimpleShape a "genericDeclareNamedSchemaUnrestricted") =>
147+ Proxy a -> Declare (Definitions Schema) NamedSchema
120148 declareNamedSchema = genericDeclareNamedSchema defaultSchemaOptions
121149
150+instance ToSchema TimeOfDay where
151+ declareNamedSchema _ = pure $ named "TimeOfDay" $ timeSchema "hh:MM:ss"
152+ & example ?~ toJSON (TimeOfDay 12 33 15)
153+
122154-- | Convert a type into a schema and declare all used schema definitions.
123−declareSchema :: ToSchema a => proxy a -> Declare (Definitions Schema) Schema
155+declareSchema :: ToSchema a => Proxy a -> Declare (Definitions Schema) Schema
124156declareSchema = fmap _namedSchemaSchema . declareNamedSchema
125157
126158-- | Convert a type into an optionally named schema.
@@ -133,8 +165,8 @@ declareSchema = fmap _namedSchemaSchema . declareNamedSchema
133165-- >>> toNamedSchema (Proxy :: Proxy Day) ^. name
134166-- Just "Day"
135167-- >>> encode (toNamedSchema (Proxy :: Proxy Day) ^. schema)
136−-- "{\"format\":\"date\",\"type\":\"string\"}"
137−toNamedSchema :: ToSchema a => proxy a -> NamedSchema
168+-- "{\"example\":\"2016-07-22\",\"format\":\"date\",\"type\":\"string\"}"
169+toNamedSchema :: ToSchema a => Proxy a -> NamedSchema
138170toNamedSchema = undeclare . declareNamedSchema
139171
140172-- | Get type's schema name according to its @'ToSchema'@ instance.
@@ -144,7 +176,7 @@ toNamedSchema = undeclare . declareNamedSchema
144176--
145177-- >>> schemaName (Proxy :: Proxy UTCTime)
146178-- Just "UTCTime"
147−schemaName :: ToSchema a => proxy a -> Maybe T.Text
179+schemaName :: ToSchema a => Proxy a -> Maybe T.Text
148180schemaName = _namedSchemaName . toNamedSchema
149181
150182-- | Convert a type into a schema.
@@ -154,7 +186,7 @@ schemaName = _namedSchemaName . toNamedSchema
154186--
155187-- >>> encode $ toSchema (Proxy :: Proxy [Day])
156188-- "{\"items\":{\"$ref\":\"#/definitions/Day\"},\"type\":\"array\"}"
157−toSchema :: ToSchema a => proxy a -> Schema
189+toSchema :: ToSchema a => Proxy a -> Schema
158190toSchema = _namedSchemaSchema . toNamedSchema
159191
160192-- | Convert a type into a referenced schema if possible.
@@ -165,7 +197,7 @@ toSchema = _namedSchemaSchema . toNamedSchema
165197--
166198-- >>> encode $ toSchemaRef (Proxy :: Proxy Day)
167199-- "{\"$ref\":\"#/definitions/Day\"}"
168−toSchemaRef :: ToSchema a => proxy a -> Referenced Schema
200+toSchemaRef :: ToSchema a => Proxy a -> Referenced Schema
169201toSchemaRef = undeclare . declareSchemaRef
170202
171203-- | Convert a type into a referenced schema if possible
@@ -175,7 +207,7 @@ toSchemaRef = undeclare . declareSchemaRef
175207-- Schema definitions are typically declared for every referenced schema.
176208-- If @'declareSchemaRef'@ returns a reference, a corresponding schema
177209-- will be declared (regardless of whether it is recusive or not).
178−declareSchemaRef :: ToSchema a => proxy a -> Declare (Definitions Schema) (Referenced Schema)
210+declareSchemaRef :: ToSchema a => Proxy a -> Declare (Definitions Schema) (Referenced Schema)
179211declareSchemaRef proxy = do
180212 case toNamedSchema proxy of
181213 NamedSchema (Just name) schema -> do
@@ -187,7 +219,7 @@ declareSchemaRef proxy = do
187219 -- have already declared it.
188220 -- If we have, we don't need to declare anything for
189221 -- this schema this time and thus simply return the reference.
190− known <- looks (HashMap.member name)
222+ known <- looks (InsOrdHashMap.member name)
191223 when (not known) $ do
192224 declare [(name, schema)]
193225 void $ declareNamedSchema proxy
@@ -206,7 +238,7 @@ inlineSchemasWhen p defs = template %~ deref
206238 where
207239 deref r@(Ref (Reference name))
208240 | p name =
209− case HashMap.lookup name defs of
241+ case InsOrdHashMap.lookup name defs of
210242 Just schema -> Inline (inlineSchemasWhen p defs schema)
211243 Nothing -> r
212244 | otherwise = r
@@ -233,11 +265,11 @@ inlineAllSchemas = inlineSchemasWhen (const True)
233265-- | Convert a type into a schema without references.
234266--
235267-- >>> encode $ toInlinedSchema (Proxy :: Proxy [Day])
236−-- "{\"items\":{\"format\":\"date\",\"type\":\"string\"},\"type\":\"array\"}"
268+-- "{\"items\":{\"example\":\"2016-07-22\",\"format\":\"date\",\"type\":\"string\"},\"type\":\"array\"}"
237269--
238270-- __WARNING:__ @'toInlinedSchema'@ will produce infinite schema
239271-- when inlining recursive schemas.
240−toInlinedSchema :: ToSchema a => proxy a -> Schema
272+toInlinedSchema :: ToSchema a => Proxy a -> Schema
241273toInlinedSchema proxy = inlineAllSchemas defs schema
242274 where
243275 (defs, schema) = runDeclare (declareSchema proxy) mempty
@@ -248,7 +280,7 @@ inlineNonRecursiveSchemas :: Data s => (Definitions Schema) -> s -> s
248280inlineNonRecursiveSchemas defs = inlineSchemasWhen nonRecursive defs
249281 where
250282 nonRecursive name =
251− case HashMap.lookup name defs of
283+ case InsOrdHashMap.lookup name defs of
252284 Just schema -> name `notElem` execDeclare (usedNames schema) mempty
253285 Nothing -> False
254286
@@ -260,22 +292,141 @@ inlineNonRecursiveSchemas defs = inlineSchemasWhen nonRecursive defs
260292 seen <- looks (name `elem`)
261293 when (not seen) $ do
262294 declare [name]
263− traverse_ usedNames (HashMap.lookup name defs)
295+ traverse_ usedNames (InsOrdHashMap.lookup name defs)
264296 Inline subschema -> usedNames subschema
265297
298+-- | Default schema for binary data (any sequence of octets).
299+binarySchema :: Schema
300+binarySchema = mempty
301+ & type_ ?~ SwaggerString
302+ & format ?~ "binary"
303+
304+-- | Default schema for binary data (base64 encoded).
305+byteSchema :: Schema
306+byteSchema = mempty
307+ & type_ ?~ SwaggerString
308+ & format ?~ "byte"
309+
310+-- | Default schema for password string.
311+-- @"password"@ format is used to hint UIs the input needs to be obscured.
312+passwordSchema :: Schema
313+passwordSchema = mempty
314+ & type_ ?~ SwaggerString
315+ & format ?~ "password"
316+
317+-- | Make an unrestrictive sketch of a @'Schema'@ based on a @'ToJSON'@ instance.
318+-- Produced schema can be used for further refinement.
319+--
320+-- >>> encode $ sketchSchema "hello"
321+-- "{\"example\":\"hello\",\"type\":\"string\"}"
322+--
323+-- >>> encode $ sketchSchema (1, 2, 3)
324+-- "{\"example\":[1,2,3],\"items\":{\"type\":\"number\"},\"type\":\"array\"}"
325+--
326+-- >>> encode $ sketchSchema ("Jack", 25)
327+-- "{\"example\":[\"Jack\",25],\"items\":[{\"type\":\"string\"},{\"type\":\"number\"}],\"type\":\"array\"}"
328+--
329+-- >>> data Person = Person { name :: String, age :: Int } deriving (Generic)
330+-- >>> instance ToJSON Person
331+-- >>> encode $ sketchSchema (Person "Jack" 25)
332+-- "{\"required\":[\"age\",\"name\"],\"properties\":{\"age\":{\"type\":\"number\"},\"name\":{\"type\":\"string\"}},\"example\":{\"age\":25,\"name\":\"Jack\"},\"type\":\"object\"}"
333+sketchSchema :: ToJSON a => a -> Schema
334+sketchSchema = sketch . toJSON
335+ where
336+ sketch Null = go Null
337+ sketch js@(Bool _) = go js
338+ sketch js = go js & example ?~ js
339+
340+ go Null = mempty & type_ ?~ SwaggerNull
341+ go (Bool _) = mempty & type_ ?~ SwaggerBoolean
342+ go (String _) = mempty & type_ ?~ SwaggerString
343+ go (Number _) = mempty & type_ ?~ SwaggerNumber
344+ go (Array xs) = mempty
345+ & type_ ?~ SwaggerArray
346+ & items ?~ case ischema of
347+ Just s -> SwaggerItemsObject (Inline s)
348+ _ -> SwaggerItemsArray (map Inline ys)
349+ where
350+ ys = map go (V.toList xs)
351+ allSame = and ((zipWith (==)) ys (tail ys))
352+
353+ ischema = case ys of
354+ (z:_) | allSame -> Just z
355+ _ -> Nothing
356+ go (Object o) = mempty
357+ & type_ ?~ SwaggerObject
358+ & required .~ HashMap.keys o
359+ & properties .~ fmap (Inline . go) (InsOrdHashMap.fromHashMap o)
360+
361+-- | Make a restrictive sketch of a @'Schema'@ based on a @'ToJSON'@ instance.
362+-- Produced schema uses as much constraints as possible.
363+--
364+-- >>> encode $ sketchStrictSchema "hello"
365+-- "{\"maxLength\":5,\"pattern\":\"hello\",\"minLength\":5,\"type\":\"string\",\"enum\":[\"hello\"]}"
366+--
367+-- >>> encode $ sketchStrictSchema (1, 2, 3)
368+-- "{\"minItems\":3,\"uniqueItems\":true,\"items\":[{\"maximum\":1,\"minimum\":1,\"multipleOf\":1,\"type\":\"number\",\"enum\":[1]},{\"maximum\":2,\"minimum\":2,\"multipleOf\":2,\"type\":\"number\",\"enum\":[2]},{\"maximum\":3,\"minimum\":3,\"multipleOf\":3,\"type\":\"number\",\"enum\":[3]}],\"maxItems\":3,\"type\":\"array\",\"enum\":[[1,2,3]]}"
369+--
370+-- >>> encode $ sketchStrictSchema ("Jack", 25)
371+-- "{\"minItems\":2,\"uniqueItems\":true,\"items\":[{\"maxLength\":4,\"pattern\":\"Jack\",\"minLength\":4,\"type\":\"string\",\"enum\":[\"Jack\"]},{\"maximum\":25,\"minimum\":25,\"multipleOf\":25,\"type\":\"number\",\"enum\":[25]}],\"maxItems\":2,\"type\":\"array\",\"enum\":[[\"Jack\",25]]}"
372+--
373+-- >>> data Person = Person { name :: String, age :: Int } deriving (Generic)
374+-- >>> instance ToJSON Person
375+-- >>> encode $ sketchStrictSchema (Person "Jack" 25)
376+-- "{\"required\":[\"age\",\"name\"],\"properties\":{\"age\":{\"maximum\":25,\"minimum\":25,\"multipleOf\":25,\"type\":\"number\",\"enum\":[25]},\"name\":{\"maxLength\":4,\"pattern\":\"Jack\",\"minLength\":4,\"type\":\"string\",\"enum\":[\"Jack\"]}},\"maxProperties\":2,\"minProperties\":2,\"type\":\"object\",\"enum\":[{\"age\":25,\"name\":\"Jack\"}]}"
377+sketchStrictSchema :: ToJSON a => a -> Schema
378+sketchStrictSchema = go . toJSON
379+ where
380+ go Null = mempty & type_ ?~ SwaggerNull
381+ go js@(Bool _) = mempty
382+ & type_ ?~ SwaggerBoolean
383+ & enum_ ?~ [js]
384+ go js@(String s) = mempty
385+ & type_ ?~ SwaggerString
386+ & maxLength ?~ fromIntegral (T.length s)
387+ & minLength ?~ fromIntegral (T.length s)
388+ & pattern ?~ s
389+ & enum_ ?~ [js]
390+ go js@(Number n) = mempty
391+ & type_ ?~ SwaggerNumber
392+ & maximum_ ?~ n
393+ & minimum_ ?~ n
394+ & multipleOf ?~ n
395+ & enum_ ?~ [js]
396+ go js@(Array xs) = mempty
397+ & type_ ?~ SwaggerArray
398+ & maxItems ?~ fromIntegral sz
399+ & minItems ?~ fromIntegral sz
400+ & items ?~ SwaggerItemsArray (map (Inline . go) (V.toList xs))
401+ & uniqueItems ?~ allUnique
402+ & enum_ ?~ [js]
403+ where
404+ sz = length xs
405+ allUnique = sz == HashSet.size (HashSet.fromList (V.toList xs))
406+ go js@(Object o) = mempty
407+ & type_ ?~ SwaggerObject
408+ & required .~ names
409+ & properties .~ fmap (Inline . go) (InsOrdHashMap.fromHashMap o)
410+ & maxProperties ?~ fromIntegral (length names)
411+ & minProperties ?~ fromIntegral (length names)
412+ & enum_ ?~ [js]
413+ where
414+ names = HashMap.keys o
415+
266416class GToSchema (f :: * -> *) where
267− gdeclareNamedSchema :: SchemaOptions -> proxy f -> Schema -> Declare (Definitions Schema) NamedSchema
417+ gdeclareNamedSchema :: SchemaOptions -> Proxy f -> Schema -> Declare (Definitions Schema) NamedSchema
268418
269419instance OVERLAPPABLE_ ToSchema a => ToSchema [a] where
270420 declareNamedSchema _ = do
271421 ref <- declareSchemaRef (Proxy :: Proxy a)
272422 return $ unnamed $ mempty
273− & type_ .~ SwaggerArray
423+ & type_ ?~ SwaggerArray
274424 & items ?~ SwaggerItemsObject ref
275425
276426instance OVERLAPPING_ ToSchema String where declareNamedSchema = plain . paramSchemaToSchema
277427instance ToSchema Bool where declareNamedSchema = plain . paramSchemaToSchema
278428instance ToSchema Integer where declareNamedSchema = plain . paramSchemaToSchema
429+instance ToSchema Natural where declareNamedSchema = plain . paramSchemaToSchema
279430instance ToSchema Int where declareNamedSchema = plain . paramSchemaToSchema
280431instance ToSchema Int8 where declareNamedSchema = plain . paramSchemaToSchema
281432instance ToSchema Int16 where declareNamedSchema = plain . paramSchemaToSchema
@@ -287,11 +438,16 @@ instance ToSchema Word16 where declareNamedSchema = plain . paramSchemaToSchema
287438instance ToSchema Word32 where declareNamedSchema = plain . paramSchemaToSchema
288439instance ToSchema Word64 where declareNamedSchema = plain . paramSchemaToSchema
289440
290−instance ToSchema Char where declareNamedSchema = plain . paramSchemaToSchema
441+instance ToSchema Char where
442+ declareNamedSchema proxy = plain (paramSchemaToSchema proxy)
443+ & mapped.Swagger.schema.example ?~ toJSON '?'
444+
291445instance ToSchema Scientific where declareNamedSchema = plain . paramSchemaToSchema
292446instance ToSchema Double where declareNamedSchema = plain . paramSchemaToSchema
293447instance ToSchema Float where declareNamedSchema = plain . paramSchemaToSchema
294448
449+instance HasResolution a => ToSchema (Fixed a) where declareNamedSchema = plain . paramSchemaToSchema
450+
295451instance ToSchema a => ToSchema (Maybe a) where
296452 declareNamedSchema _ = declareNamedSchema (Proxy :: Proxy a)
297453
@@ -300,6 +456,11 @@ instance (ToSchema a, ToSchema b) => ToSchema (Either a b)
300456instance ToSchema () where
301457 declareNamedSchema _ = pure (NamedSchema Nothing nullarySchema)
302458
459+-- | For 'ToJSON' instance, see <http://hackage.haskell.org/package/uuid-aeson uuid-aeson> package.
460+instance ToSchema UUID.UUID where
461+ declareNamedSchema p = pure $ named "UUID" $ paramSchemaToSchema p
462+ & example ?~ toJSON (UUID.toText UUID.nil)
463+
303464instance (ToSchema a, ToSchema b) => ToSchema (a, b)
304465instance (ToSchema a, ToSchema b, ToSchema c) => ToSchema (a, b, c)
305466instance (ToSchema a, ToSchema b, ToSchema c, ToSchema d) => ToSchema (a, b, c, d)
@@ -309,46 +470,81 @@ instance (ToSchema a, ToSchema b, ToSchema c, ToSchema d, ToSchema e, ToSchema f
309470
310471timeSchema :: T.Text -> Schema
311472timeSchema fmt = mempty
312− & type_ .~ SwaggerString
473+ & type_ ?~ SwaggerString
313474 & format ?~ fmt
314475
315476-- | Format @"date"@ corresponds to @yyyy-mm-dd@ format.
316477instance ToSchema Day where
317− declareNamedSchema _ = pure $ named "Day" (timeSchema "date")
478+ declareNamedSchema _ = pure $ named "Day" $ timeSchema "date"
479+ & example ?~ toJSON (fromGregorian 2016 7 22)
318480
319481-- |
320482-- >>> toSchema (Proxy :: Proxy LocalTime) ^. format
321483-- Just "yyyy-mm-ddThh:MM:ss"
322484instance ToSchema LocalTime where
323− declareNamedSchema _ = pure $ named "LocalTime" (timeSchema "yyyy-mm-ddThh:MM:ss")
485+ declareNamedSchema _ = pure $ named "LocalTime" $ timeSchema "yyyy-mm-ddThh:MM:ss"
486+ & example ?~ toJSON (LocalTime (fromGregorian 2016 7 22) (TimeOfDay 7 40 0))
324487
325488-- | Format @"date"@ corresponds to @yyyy-mm-ddThh:MM:ss(Z|+hh:MM)@ format.
326489instance ToSchema ZonedTime where
327490 declareNamedSchema _ = pure $ named "ZonedTime" $ timeSchema "date-time"
491+ & example ?~ toJSON (ZonedTime (LocalTime (fromGregorian 2016 7 22) (TimeOfDay 7 40 0)) (hoursToTimeZone 3))
328492
329493instance ToSchema NominalDiffTime where
330− declareNamedSchema _ = declareNamedSchema (Proxy :: Proxy Integer)
494+ declareNamedSchema _ = declareNamedSchema (Proxy :: Proxy Pico)
331495
332496-- |
333497-- >>> toSchema (Proxy :: Proxy UTCTime) ^. format
334498-- Just "yyyy-mm-ddThh:MM:ssZ"
335499instance ToSchema UTCTime where
336− declareNamedSchema _ = pure $ named "UTCTime" (timeSchema "yyyy-mm-ddThh:MM:ssZ")
500+ declareNamedSchema _ = pure $ named "UTCTime" $ timeSchema "yyyy-mm-ddThh:MM:ssZ"
501+ & example ?~ toJSON (UTCTime (fromGregorian 2016 7 22) 0)
337502
338503instance ToSchema T.Text where declareNamedSchema = plain . paramSchemaToSchema
339504instance ToSchema TL.Text where declareNamedSchema = plain . paramSchemaToSchema
340505
506+instance ToSchema Version where declareNamedSchema = plain . paramSchemaToSchema
507+
508+#if __GLASGOW_HASKELL__ < 800
509+#else
510+type family ToSchemaByteStringError bs where
511+ ToSchemaByteStringError bs = TypeError
512+ ( Text "Impossible to have an instance " :<>: ShowType (ToSchema bs) :<>: Text "."
513+ :$$: Text "Please, use a newtype wrapper around " :<>: ShowType bs :<>: Text " instead."
514+ :$$: Text "Consider using byteSchema or binarySchema templates." )
515+
516+instance ToSchemaByteStringError BS.ByteString => ToSchema BS.ByteString where declareNamedSchema = error "impossible"
517+instance ToSchemaByteStringError BSL.ByteString => ToSchema BSL.ByteString where declareNamedSchema = error "impossible"
518+#endif
519+
341520instance ToSchema IntSet where declareNamedSchema _ = declareNamedSchema (Proxy :: Proxy (Set Int))
342521
343522-- | NOTE: This schema does not account for the uniqueness of keys.
344523instance ToSchema a => ToSchema (IntMap a) where
345524 declareNamedSchema _ = declareNamedSchema (Proxy :: Proxy [(Int, a)])
346525
526+#if MIN_VERSION_aeson(1,0,0)
527+instance (ToJSONKey k, ToSchema k, ToSchema v) => ToSchema (Map k v) where
528+ declareNamedSchema _ = case toJSONKey :: ToJSONKeyFunction k of
529+ ToJSONKeyText _ _ -> declareObjectMapSchema
530+ ToJSONKeyValue _ _ -> declareNamedSchema (Proxy :: Proxy [(k, v)])
531+ where
532+ declareObjectMapSchema = do
533+ schema <- declareSchemaRef (Proxy :: Proxy v)
534+ return $ unnamed $ mempty
535+ & type_ ?~ SwaggerObject
536+ & additionalProperties ?~ AdditionalPropertiesSchema schema
537+
538+instance (ToJSONKey k, ToSchema k, ToSchema v) => ToSchema (HashMap k v) where
539+ declareNamedSchema _ = declareNamedSchema (Proxy :: Proxy (Map k v))
540+
541+#else
542+
347543instance ToSchema a => ToSchema (Map String a) where
348544 declareNamedSchema _ = do
349− schema <- declareSchema (Proxy :: Proxy a)
545+ schema <- declareSchemaRef (Proxy :: Proxy a)
350546 return $ unnamed $ mempty
351− & type_ .~ SwaggerObject
547+ & type_ ?~ SwaggerObject
352548 & additionalProperties ?~ schema
353549
354550instance ToSchema a => ToSchema (Map T.Text a) where declareNamedSchema _ = declareNamedSchema (Proxy :: Proxy (Map String a))
@@ -358,6 +554,19 @@ instance ToSchema a => ToSchema (HashMap String a) where declareNamedSchema _ =
358554instance ToSchema a => ToSchema (HashMap T.Text a) where declareNamedSchema _ = declareNamedSchema (Proxy :: Proxy (Map String a))
359555instance ToSchema a => ToSchema (HashMap TL.Text a) where declareNamedSchema _ = declareNamedSchema (Proxy :: Proxy (Map String a))
360556
557+#endif
558+
559+instance OVERLAPPING_ ToSchema Object where
560+ declareNamedSchema _ = pure $ NamedSchema (Just "Object") $ mempty
561+ & type_ ?~ SwaggerObject
562+ & description ?~ "Arbitrary JSON object."
563+ & additionalProperties ?~ AdditionalPropertiesAllowed True
564+
565+instance ToSchema a => ToSchema (V.Vector a) where declareNamedSchema _ = declareNamedSchema (Proxy :: Proxy [a])
566+instance ToSchema a => ToSchema (VU.Vector a) where declareNamedSchema _ = declareNamedSchema (Proxy :: Proxy [a])
567+instance ToSchema a => ToSchema (VS.Vector a) where declareNamedSchema _ = declareNamedSchema (Proxy :: Proxy [a])
568+instance ToSchema a => ToSchema (VP.Vector a) where declareNamedSchema _ = declareNamedSchema (Proxy :: Proxy [a])
569+
361570instance ToSchema a => ToSchema (Set a) where
362571 declareNamedSchema _ = do
363572 schema <- declareSchema (Proxy :: Proxy [a])
@@ -366,6 +575,13 @@ instance ToSchema a => ToSchema (Set a) where
366575
367576instance ToSchema a => ToSchema (HashSet a) where declareNamedSchema _ = declareNamedSchema (Proxy :: Proxy (Set a))
368577
578+-- | @since 2.2.1
579+instance ToSchema a => ToSchema (NonEmpty a) where
580+ declareNamedSchema _ = do
581+ schema <- declareSchema (Proxy :: Proxy [a])
582+ return $ unnamed $ schema
583+ & minItems .~ Just 1
584+
369585instance ToSchema All where declareNamedSchema = plain . paramSchemaToSchema
370586instance ToSchema Any where declareNamedSchema = plain . paramSchemaToSchema
371587
@@ -375,67 +591,147 @@ instance ToSchema a => ToSchema (First a) where declareNamedSchema _ = unname
375591instance ToSchema a => ToSchema (Last a) where declareNamedSchema _ = unname <$> declareNamedSchema (Proxy :: Proxy a)
376592instance ToSchema a => ToSchema (Dual a) where declareNamedSchema _ = unname <$> declareNamedSchema (Proxy :: Proxy a)
377593
594+instance ToSchema a => ToSchema (Identity a) where declareNamedSchema _ = declareNamedSchema (Proxy :: Proxy a)
595+
378596-- | Default schema for @'Bounded'@, @'Integral'@ types.
379597--
380598-- >>> encode $ toSchemaBoundedIntegral (Proxy :: Proxy Int16)
381599-- "{\"maximum\":32767,\"minimum\":-32768,\"type\":\"integer\"}"
382−toSchemaBoundedIntegral :: forall a proxy. (Bounded a, Integral a) => proxy a -> Schema
600+toSchemaBoundedIntegral :: forall a. (Bounded a, Integral a) => Proxy a -> Schema
383601toSchemaBoundedIntegral _ = mempty
384− & type_ .~ SwaggerInteger
602+ & type_ ?~ SwaggerInteger
385603 & minimum_ ?~ fromInteger (toInteger (minBound :: a))
386604 & maximum_ ?~ fromInteger (toInteger (maxBound :: a))
387605
388606-- | Default generic named schema for @'Bounded'@, @'Integral'@ types.
389−genericToNamedSchemaBoundedIntegral :: forall a d f proxy.
607+genericToNamedSchemaBoundedIntegral :: forall a d f.
390608 ( Bounded a, Integral a
391609 , Generic a, Rep a ~ D1 d f, Datatype d)
392− => SchemaOptions -> proxy a -> NamedSchema
610+ => SchemaOptions -> Proxy a -> NamedSchema
393611genericToNamedSchemaBoundedIntegral opts proxy
394− = NamedSchema (gdatatypeSchemaName opts (Proxy :: Proxy d)) (toSchemaBoundedIntegral proxy)
612+ = genericNameSchema opts proxy (toSchemaBoundedIntegral proxy)
613+
614+-- | Declare a named schema for a @newtype@ wrapper.
615+genericDeclareNamedSchemaNewtype :: forall a d c s i inner.
616+ (Generic a, Datatype d, Rep a ~ D1 d (C1 c (S1 s (K1 i inner))))
617+ => SchemaOptions -- ^ How to derive the name.
618+ -> (Proxy inner -> Declare (Definitions Schema) Schema) -- ^ How to create a schema for the wrapped type.
619+ -> Proxy a
620+ -> Declare (Definitions Schema) NamedSchema
621+genericDeclareNamedSchemaNewtype opts f proxy = genericNameSchema opts proxy <$> f (Proxy :: Proxy inner)
622+
623+-- | Declare 'Schema' for a mapping with 'Bounded' 'Enum' keys.
624+-- This makes a much more useful schema when there aren't many options for key values.
625+--
626+-- >>> data ButtonState = Neutral | Focus | Active | Hover | Disabled deriving (Show, Bounded, Enum, Generic)
627+-- >>> instance ToJSON ButtonState
628+-- >>> instance ToSchema ButtonState
629+-- >>> instance ToJSONKey ButtonState where toJSONKey = toJSONKeyText (T.pack . show)
630+-- >>> type ImageUrl = T.Text
631+-- >>> encode $ toSchemaBoundedEnumKeyMapping (Proxy :: Proxy (Map ButtonState ImageUrl))
632+-- "{\"properties\":{\"Neutral\":{\"type\":\"string\"},\"Focus\":{\"type\":\"string\"},\"Active\":{\"type\":\"string\"},\"Hover\":{\"type\":\"string\"},\"Disabled\":{\"type\":\"string\"}},\"type\":\"object\"}"
633+--
634+-- Note: this is only useful when @key@ is encoded with 'ToJSONKeyText'.
635+-- If it is encoded with 'ToJSONKeyValue' then a regular schema for @[(key, value)]@ is used.
636+declareSchemaBoundedEnumKeyMapping :: forall map key value.
637+ (Bounded key, Enum key, ToJSONKey key, ToSchema key, ToSchema value)
638+ => Proxy (map key value) -> Declare (Definitions Schema) Schema
639+declareSchemaBoundedEnumKeyMapping _ = case toJSONKey :: ToJSONKeyFunction key of
640+ ToJSONKeyText keyToText _ -> objectSchema keyToText
641+ ToJSONKeyValue _ _ -> declareSchema (Proxy :: Proxy [(key, value)])
642+ where
643+ objectSchema keyToText = do
644+ valueRef <- declareSchemaRef (Proxy :: Proxy value)
645+ let allKeys = [minBound..maxBound :: key]
646+ mkPair k = (keyToText k, valueRef)
647+ return $ mempty
648+ & type_ ?~ SwaggerObject
649+ & properties .~ InsOrdHashMap.fromList (map mkPair allKeys)
650+
651+-- | A 'Schema' for a mapping with 'Bounded' 'Enum' keys.
652+-- This makes a much more useful schema when there aren't many options for key values.
653+--
654+-- >>> data ButtonState = Neutral | Focus | Active | Hover | Disabled deriving (Show, Bounded, Enum, Generic)
655+-- >>> instance ToJSON ButtonState
656+-- >>> instance ToSchema ButtonState
657+-- >>> instance ToJSONKey ButtonState where toJSONKey = toJSONKeyText (T.pack . show)
658+-- >>> type ImageUrl = T.Text
659+-- >>> encode $ toSchemaBoundedEnumKeyMapping (Proxy :: Proxy (Map ButtonState ImageUrl))
660+-- "{\"properties\":{\"Neutral\":{\"type\":\"string\"},\"Focus\":{\"type\":\"string\"},\"Active\":{\"type\":\"string\"},\"Hover\":{\"type\":\"string\"},\"Disabled\":{\"type\":\"string\"}},\"type\":\"object\"}"
661+--
662+-- Note: this is only useful when @key@ is encoded with 'ToJSONKeyText'.
663+-- If it is encoded with 'ToJSONKeyValue' then a regular schema for @[(key, value)]@ is used.
664+toSchemaBoundedEnumKeyMapping :: forall map key value.
665+ (Bounded key, Enum key, ToJSONKey key, ToSchema key, ToSchema value)
666+ => Proxy (map key value) -> Schema
667+toSchemaBoundedEnumKeyMapping = flip evalDeclare mempty . declareSchemaBoundedEnumKeyMapping
395668
396669-- | A configurable generic @'Schema'@ creator.
397−genericDeclareSchema :: (Generic a, GToSchema (Rep a)) => SchemaOptions -> proxy a -> Declare (Definitions Schema) Schema
398−genericDeclareSchema opts proxy = _namedSchemaSchema <$> genericDeclareNamedSchema opts proxy
670+genericDeclareSchema :: (Generic a, GToSchema (Rep a), TypeHasSimpleShape a "genericDeclareSchemaUnrestricted") =>
671+ SchemaOptions -> Proxy a -> Declare (Definitions Schema) Schema
672+genericDeclareSchema = genericDeclareSchemaUnrestricted
399673
400674-- | A configurable generic @'NamedSchema'@ creator.
401675-- This function applied to @'defaultSchemaOptions'@
402676-- is used as the default for @'declareNamedSchema'@
403677-- when the type is an instance of @'Generic'@.
404−genericDeclareNamedSchema :: forall a proxy. (Generic a, GToSchema (Rep a)) => SchemaOptions -> proxy a -> Declare (Definitions Schema) NamedSchema
405−genericDeclareNamedSchema opts _ = gdeclareNamedSchema opts (Proxy :: Proxy (Rep a)) mempty
678+genericDeclareNamedSchema :: (Generic a, GToSchema (Rep a), TypeHasSimpleShape a "genericDeclareNamedSchemaUnrestricted") =>
679+ SchemaOptions -> Proxy a -> Declare (Definitions Schema) NamedSchema
680+genericDeclareNamedSchema = genericDeclareNamedSchemaUnrestricted
406681
407−gdatatypeSchemaName :: forall proxy d. Datatype d => SchemaOptions -> proxy d -> Maybe T.Text
408−gdatatypeSchemaName opts _ = case name of
682+-- | A configurable generic @'Schema'@ creator.
683+--
684+-- Unlike 'genericDeclareSchema' also works for mixed sum types.
685+-- Use with care since some Swagger tools do not support well schemas for mixed sum types.
686+genericDeclareSchemaUnrestricted :: (Generic a, GToSchema (Rep a)) => SchemaOptions -> Proxy a -> Declare (Definitions Schema) Schema
687+genericDeclareSchemaUnrestricted opts proxy = _namedSchemaSchema <$> genericDeclareNamedSchemaUnrestricted opts proxy
688+
689+-- | A configurable generic @'NamedSchema'@ creator.
690+--
691+-- Unlike 'genericDeclareNamedSchema' also works for mixed sum types.
692+-- Use with care since some Swagger tools do not support well schemas for mixed sum types.
693+genericDeclareNamedSchemaUnrestricted :: forall a. (Generic a, GToSchema (Rep a)) =>
694+ SchemaOptions -> Proxy a -> Declare (Definitions Schema) NamedSchema
695+genericDeclareNamedSchemaUnrestricted opts _ = gdeclareNamedSchema opts (Proxy :: Proxy (Rep a)) mempty
696+
697+-- | Derive a 'Generic'-based name for a datatype and assign it to a given 'Schema'.
698+genericNameSchema :: forall a d f.
699+ (Generic a, Rep a ~ D1 d f, Datatype d)
700+ => SchemaOptions -> Proxy a -> Schema -> NamedSchema
701+genericNameSchema opts _ = NamedSchema (gdatatypeSchemaName opts (Proxy :: Proxy d))
702+
703+gdatatypeSchemaName :: forall d. Datatype d => SchemaOptions -> Proxy d -> Maybe T.Text
704+gdatatypeSchemaName opts _ = case orig of
409705 (c:_) | isAlpha c && isUpper c -> Just (T.pack name)
410706 _ -> Nothing
411707 where
412− name = datatypeNameModifier opts (datatypeName (Proxy3 :: Proxy3 d f a))
708+ orig = datatypeName (Proxy3 :: Proxy3 d f a)
709+ name = datatypeNameModifier opts orig
413710
414711-- | Lift a plain @'ParamSchema'@ into a model @'NamedSchema'@.
415−paramSchemaToNamedSchema :: forall a d f proxy.
416− (ToParamSchema a, Generic a, Rep a ~ D1 d f, Datatype d)
417− => SchemaOptions -> proxy a -> NamedSchema
418−paramSchemaToNamedSchema opts proxy = NamedSchema (gdatatypeSchemaName opts (Proxy :: Proxy d)) (paramSchemaToSchema proxy)
712+paramSchemaToNamedSchema :: (ToParamSchema a, Generic a, Rep a ~ D1 d f, Datatype d) =>
713+ SchemaOptions -> Proxy a -> NamedSchema
714+paramSchemaToNamedSchema opts proxy = genericNameSchema opts proxy (paramSchemaToSchema proxy)
419715
420716-- | Lift a plain @'ParamSchema'@ into a model @'Schema'@.
421−paramSchemaToSchema :: forall a proxy. ToParamSchema a => proxy a -> Schema
422−paramSchemaToSchema _ = mempty & paramSchema .~ toParamSchema (Proxy :: Proxy a)
717+paramSchemaToSchema :: ToParamSchema a => Proxy a -> Schema
718+paramSchemaToSchema proxy = mempty & paramSchema .~ toParamSchema proxy
423719
424720nullarySchema :: Schema
425721nullarySchema = mempty
426− & type_ .~ SwaggerArray
722+ & type_ ?~ SwaggerArray
427723 & items ?~ SwaggerItemsArray []
428724
429−gtoNamedSchema :: GToSchema f => SchemaOptions -> proxy f -> NamedSchema
725+gtoNamedSchema :: GToSchema f => SchemaOptions -> Proxy f -> NamedSchema
430726gtoNamedSchema opts proxy = undeclare $ gdeclareNamedSchema opts proxy mempty
431727
432−gdeclareSchema :: GToSchema f => SchemaOptions -> proxy f -> Declare (Definitions Schema) Schema
728+gdeclareSchema :: GToSchema f => SchemaOptions -> Proxy f -> Declare (Definitions Schema) Schema
433729gdeclareSchema opts proxy = _namedSchemaSchema <$> gdeclareNamedSchema opts proxy mempty
434730
435731instance (GToSchema f, GToSchema g) => GToSchema (f :*: g) where
436732 gdeclareNamedSchema opts _ schema = do
437− NamedSchema _ gschema <- gdeclareNamedSchema opts (Proxy :: Proxy g) schema
438− gdeclareNamedSchema opts (Proxy :: Proxy f) gschema
733+ NamedSchema _ gschema <- gdeclareNamedSchema opts (Proxy :: Proxy f) schema
734+ gdeclareNamedSchema opts (Proxy :: Proxy g) gschema
439735
440736instance (Datatype d, GToSchema f) => GToSchema (D1 d f) where
441737 gdeclareNamedSchema opts _ s = rename name <$> gdeclareNamedSchema opts (Proxy :: Proxy f) s
@@ -449,7 +745,7 @@ instance OVERLAPPING_ Constructor c => GToSchema (C1 c U1) where
449745 gdeclareNamedSchema = gdeclareNamedSumSchema
450746
451747-- | Single field constructor.
452−instance (Selector s, GToSchema f) => GToSchema (C1 c (S1 s f)) where
748+instance (Selector s, GToSchema f, GToSchema (S1 s f)) => GToSchema (C1 c (S1 s f)) where
453749 gdeclareNamedSchema opts _ s
454750 | unwrapUnaryRecords opts = fieldSchema
455751 | otherwise =
@@ -463,7 +759,7 @@ instance (Selector s, GToSchema f) => GToSchema (C1 c (S1 s f)) where
463759 recordSchema = gdeclareNamedSchema opts (Proxy :: Proxy (S1 s f)) s
464760 fieldSchema = gdeclareNamedSchema opts (Proxy :: Proxy f) s
465761
466−gdeclareSchemaRef :: GToSchema a => SchemaOptions -> proxy a -> Declare (Definitions Schema) (Referenced Schema)
762+gdeclareSchemaRef :: GToSchema a => SchemaOptions -> Proxy a -> Declare (Definitions Schema) (Referenced Schema)
467763gdeclareSchemaRef opts proxy = do
468764 case gtoNamedSchema opts proxy of
469765 NamedSchema (Just name) schema -> do
@@ -475,16 +771,16 @@ gdeclareSchemaRef opts proxy = do
475771 -- have already declared it.
476772 -- If we have, we don't need to declare anything for
477773 -- this schema this time and thus simply return the reference.
478− known <- looks (HashMap.member name)
774+ known <- looks (InsOrdHashMap.member name)
479775 when (not known) $ do
480776 declare [(name, schema)]
481777 void $ gdeclareNamedSchema opts proxy mempty
482778 return $ Ref (Reference name)
483779 _ -> Inline <$> gdeclareSchema opts proxy
484780
485−appendItem :: Referenced Schema -> Maybe (SwaggerItems Schema) -> Maybe (SwaggerItems Schema)
781+appendItem :: Referenced Schema -> Maybe (SwaggerItems 'SwaggerKindSchema) -> Maybe (SwaggerItems 'SwaggerKindSchema)
486782appendItem x Nothing = Just (SwaggerItemsArray [x])
487−appendItem x (Just (SwaggerItemsArray xs)) = Just (SwaggerItemsArray (x:xs))
783+appendItem x (Just (SwaggerItemsArray xs)) = Just (SwaggerItemsArray (xs ++ [x]))
488784appendItem _ _ = error "GToSchema.appendItem: cannot append to SwaggerItemsObject"
489785
490786withFieldSchema :: forall proxy s f. (Selector s, GToSchema f) =>
@@ -494,13 +790,15 @@ withFieldSchema opts _ isRequiredField schema = do
494790 return $
495791 if T.null fname
496792 then schema
497− & type_ .~ SwaggerArray
793+ & type_ ?~ SwaggerArray
498794 & items %~ appendItem ref
795+ & maxItems %~ Just . maybe 1 (+1) -- increment maxItems
796+ & minItems %~ Just . maybe 1 (+1) -- increment minItems
499797 else schema
500− & type_ .~ SwaggerObject
798+ & type_ ?~ SwaggerObject
501799 & properties . at fname ?~ ref
502800 & if isRequiredField
503− then required %~ (fname :)
801+ then required %~ (++ [fname])
504802 else id
505803 where
506804 fname = T.pack (fieldLabelModifier opts (selName (Proxy3 :: Proxy3 s f p)))
@@ -519,10 +817,13 @@ instance OVERLAPPING_ ToSchema c => GToSchema (K1 i (Maybe c)) where
519817instance OVERLAPPABLE_ ToSchema c => GToSchema (K1 i c) where
520818 gdeclareNamedSchema _ _ _ = declareNamedSchema (Proxy :: Proxy c)
521819
522−instance (GSumToSchema f, GSumToSchema g) => GToSchema (f :+: g) where
820+instance ( GSumToSchema f
821+ , GSumToSchema g
822+ ) => GToSchema (f :+: g)
823+ where
523824 gdeclareNamedSchema = gdeclareNamedSumSchema
524825
525−gdeclareNamedSumSchema :: GSumToSchema f => SchemaOptions -> proxy f -> Schema -> Declare (Definitions Schema) NamedSchema
826+gdeclareNamedSumSchema :: GSumToSchema f => SchemaOptions -> Proxy f -> Schema -> Declare (Definitions Schema) NamedSchema
526827gdeclareNamedSumSchema opts proxy s
527828 | allNullaryToStringTag opts && allNullary = pure $ unnamed (toStringTag sumSchema)
528829 | otherwise = (unnamed . fst) <$> runWriterT declareSumSchema
@@ -531,29 +832,29 @@ gdeclareNamedSumSchema opts proxy s
531832 (sumSchema, All allNullary) = undeclare (runWriterT declareSumSchema)
532833
533834 toStringTag schema = mempty
534− & type_ .~ SwaggerString
535− & enum_ ?~ map toJSON (schema ^.. properties.ifolded.asIndex)
835+ & type_ ?~ SwaggerString
836+ & enum_ ?~ map toJSON (schema ^.. properties.ifolded.asIndex)
536837
537838type AllNullary = All
538839
539−class GSumToSchema f where
540− gsumToSchema :: SchemaOptions -> proxy f -> Schema -> WriterT AllNullary (Declare (Definitions Schema)) Schema
840+class GSumToSchema (f :: * -> *) where
841+ gsumToSchema :: SchemaOptions -> Proxy f -> Schema -> WriterT AllNullary (Declare (Definitions Schema)) Schema
541842
542843instance (GSumToSchema f, GSumToSchema g) => GSumToSchema (f :+: g) where
543− gsumToSchema opts _ = gsumToSchema opts (Proxy :: Proxy f) <=< gsumToSchema opts (Proxy :: Proxy g)
844+ gsumToSchema opts _ = gsumToSchema opts (Proxy :: Proxy f) >=> gsumToSchema opts (Proxy :: Proxy g)
544845
545−gsumConToSchemaWith :: forall c f proxy. (GToSchema (C1 c f), Constructor c) =>
546− Referenced Schema -> SchemaOptions -> proxy (C1 c f) -> Schema -> Schema
846+gsumConToSchemaWith :: forall c f. (GToSchema (C1 c f), Constructor c) =>
847+ Referenced Schema -> SchemaOptions -> Proxy (C1 c f) -> Schema -> Schema
547848gsumConToSchemaWith ref opts _ schema = schema
548− & type_ .~ SwaggerObject
849+ & type_ ?~ SwaggerObject
549850 & properties . at tag ?~ ref
550851 & maxProperties ?~ 1
551852 & minProperties ?~ 1
552853 where
553854 tag = T.pack (constructorTagModifier opts (conName (Proxy3 :: Proxy3 c f p)))
554855
555−gsumConToSchema :: forall c f proxy. (GToSchema (C1 c f), Constructor c) =>
556− SchemaOptions -> proxy (C1 c f) -> Schema -> Declare (Definitions Schema) Schema
856+gsumConToSchema :: (GToSchema (C1 c f), Constructor c) =>
857+ SchemaOptions -> Proxy (C1 c f) -> Schema -> Declare (Definitions Schema) Schema
557858gsumConToSchema opts proxy schema = do
558859 ref <- gdeclareSchemaRef opts proxy
559860 return $ gsumConToSchemaWith ref opts proxy schema
@@ -575,3 +876,7 @@ data Proxy2 a b = Proxy2
575876
576877data Proxy3 a b c = Proxy3
577878
879+-- $setup
880+-- >>> import Data.Swagger
881+-- >>> import Data.Aeson (encode)
882+-- >>> import Data.Aeson.Types (toJSONKeyText)
src/Data/Swagger/Internal/Schema/Validation.hsnew file+511
@@ -0,0 +1,511 @@
1+{-# OPTIONS_GHC -Wall #-}
2+{-# LANGUAGE DataKinds #-}
3+{-# LANGUAGE DeriveFunctor #-}
4+{-# LANGUAGE FlexibleInstances #-}
5+{-# LANGUAGE FunctionalDependencies #-}
6+{-# LANGUAGE GADTs #-}
7+{-# LANGUAGE GeneralizedNewtypeDeriving #-}
8+{-# LANGUAGE LambdaCase #-}
9+{-# LANGUAGE MultiParamTypeClasses #-}
10+{-# LANGUAGE PackageImports #-}
11+{-# LANGUAGE RankNTypes #-}
12+{-# LANGUAGE ScopedTypeVariables #-}
13+{-# LANGUAGE TemplateHaskell #-}
14+{-# LANGUAGE UndecidableInstances #-}
15+-- |
16+-- Module: Data.Swagger.Internal.Schema.Validation
17+-- Copyright: (c) 2015 GetShopTV
18+-- License: BSD3
19+-- Maintainer: Nickolay Kudasov <nickolay@getshoptv.com>
20+-- Stability: experimental
21+--
22+-- Validate JSON values with Swagger Schema.
23+module Data.Swagger.Internal.Schema.Validation where
24+
25+import Prelude ()
26+import Prelude.Compat
27+
28+import Control.Applicative
29+import Control.Lens
30+import Control.Monad (when)
31+
32+import Data.Aeson hiding (Result)
33+import Data.Aeson.Encode.Pretty (encodePretty)
34+import Data.Foldable (for_, sequenceA_,
35+ traverse_)
36+import Data.HashMap.Strict (HashMap)
37+import qualified Data.HashMap.Strict as HashMap
38+import qualified Data.HashMap.Strict.InsOrd as InsOrdHashMap
39+import qualified "unordered-containers" Data.HashSet as HashSet
40+import Data.Proxy
41+import Data.Scientific (Scientific, isInteger)
42+import Data.Text (Text)
43+import qualified Data.Text as Text
44+import qualified Data.Text.Lazy as TL
45+import qualified Data.Text.Lazy.Encoding as TL
46+import Data.Vector (Vector)
47+import qualified Data.Vector as Vector
48+
49+import Data.Swagger.Declare
50+import Data.Swagger.Internal
51+import Data.Swagger.Internal.Schema
52+import Data.Swagger.Lens
53+
54+-- | Validate @'ToJSON'@ instance matches @'ToSchema'@ for a given value.
55+-- This can be used with QuickCheck to ensure those instances are coherent:
56+--
57+-- prop> validateToJSON (x :: Int) == []
58+--
59+-- /NOTE:/ @'validateToJSON'@ does not perform string pattern validation.
60+-- See @'validateToJSONWithPatternChecker'@.
61+--
62+-- See 'renderValidationErrors' on how the output is structured.
63+validatePrettyToJSON :: forall a. (ToJSON a, ToSchema a) => a -> Maybe String
64+validatePrettyToJSON = renderValidationErrors validateToJSON
65+
66+-- | Variant of 'validatePrettyToJSON' with typed output.
67+validateToJSON :: forall a. (ToJSON a, ToSchema a) => a -> [ValidationError]
68+validateToJSON = validateToJSONWithPatternChecker (\_pattern _str -> True)
69+
70+-- | Validate @'ToJSON'@ instance matches @'ToSchema'@ for a given value and pattern checker.
71+-- This can be used with QuickCheck to ensure those instances are coherent.
72+--
73+-- For validation without patterns see @'validateToJSON'@. See also:
74+-- 'renderValidationErrors'.
75+validateToJSONWithPatternChecker :: forall a. (ToJSON a, ToSchema a) => (Pattern -> Text -> Bool) -> a -> [ValidationError]
76+validateToJSONWithPatternChecker checker = validateJSONWithPatternChecker checker defs sch . toJSON
77+ where
78+ (defs, sch) = runDeclare (declareSchema (Proxy :: Proxy a)) mempty
79+
80+-- | Pretty print validation errors
81+-- together with actual JSON and Swagger Schema
82+-- (using 'encodePretty').
83+--
84+-- >>> import Data.Aeson as Aeson
85+-- >>> import Data.Foldable (traverse_)
86+-- >>> import GHC.Generics
87+-- >>> data Phone = Phone { value :: String } deriving (Generic)
88+-- >>> data Person = Person { name :: String, phone :: Phone } deriving (Generic)
89+-- >>> instance ToJSON Person where toJSON p = object [ "name" Aeson..= name p ]
90+-- >>> instance ToSchema Phone
91+-- >>> instance ToSchema Person
92+-- >>> let person = Person { name = "John", phone = Phone "123456" }
93+-- >>> traverse_ putStrLn $ renderValidationErrors validateToJSON person
94+-- Validation against the schema fails:
95+-- * property "phone" is required, but not found in "{\"name\":\"John\"}"
96+-- <BLANKLINE>
97+-- JSON value:
98+-- {
99+-- "name": "John"
100+-- }
101+-- <BLANKLINE>
102+-- Swagger Schema:
103+-- {
104+-- "required": [
105+-- "name",
106+-- "phone"
107+-- ],
108+-- "type": "object",
109+-- "properties": {
110+-- "phone": {
111+-- "$ref": "#/definitions/Phone"
112+-- },
113+-- "name": {
114+-- "type": "string"
115+-- }
116+-- }
117+-- }
118+-- <BLANKLINE>
119+-- Swagger Description Context:
120+-- {
121+-- "Phone": {
122+-- "required": [
123+-- "value"
124+-- ],
125+-- "type": "object",
126+-- "properties": {
127+-- "value": {
128+-- "type": "string"
129+-- }
130+-- }
131+-- }
132+-- }
133+-- <BLANKLINE>
134+renderValidationErrors
135+ :: forall a. (ToJSON a, ToSchema a)
136+ => (a -> [ValidationError]) -> a -> Maybe String
137+renderValidationErrors f x =
138+ case f x of
139+ [] -> Nothing
140+ errors -> Just $ unlines
141+ [ "Validation against the schema fails:"
142+ , unlines (map (" * " ++) errors)
143+ , "JSON value:"
144+ , ppJSONString (toJSON x)
145+ , ""
146+ , "Swagger Schema:"
147+ , ppJSONString (toJSON schema_)
148+ , ""
149+ , "Swagger Description Context:"
150+ , ppJSONString (toJSON refs_)
151+ ]
152+ where
153+ ppJSONString = TL.unpack . TL.decodeUtf8 . encodePretty
154+ (refs_, schema_) = runDeclare (declareSchema (Proxy :: Proxy a)) mempty
155+
156+-- | Validate JSON @'Value'@ against Swagger @'Schema'@.
157+--
158+-- prop> validateJSON mempty (toSchema (Proxy :: Proxy Int)) (toJSON (x :: Int)) == []
159+--
160+-- /NOTE:/ @'validateJSON'@ does not perform string pattern validation.
161+-- See @'validateJSONWithPatternChecker'@.
162+validateJSON :: Definitions Schema -> Schema -> Value -> [ValidationError]
163+validateJSON = validateJSONWithPatternChecker (\_pattern _str -> True)
164+
165+-- | Validate JSON @'Value'@ agains Swagger @'ToSchema'@ for a given value and pattern checker.
166+--
167+-- For validation without patterns see @'validateJSON'@.
168+validateJSONWithPatternChecker :: (Pattern -> Text -> Bool) -> Definitions Schema -> Schema -> Value -> [ValidationError]
169+validateJSONWithPatternChecker checker defs sch js =
170+ case runValidation (validateWithSchema js) cfg sch of
171+ Failed xs -> xs
172+ Passed _ -> mempty
173+ where
174+ cfg = defaultConfig
175+ { configPatternChecker = checker
176+ , configDefinitions = defs }
177+
178+-- | Validation error message.
179+type ValidationError = String
180+
181+-- | Validation result type.
182+data Result a
183+ = Failed [ValidationError] -- ^ Validation failed with a list of error messages.
184+ | Passed a -- ^ Validation passed.
185+ deriving (Eq, Show, Functor)
186+
187+instance Applicative Result where
188+ pure = Passed
189+ Passed f <*> Passed x = Passed (f x)
190+ Failed xs <*> Failed ys = Failed (xs <> ys)
191+ Failed xs <*> _ = Failed xs
192+ _ <*> Failed ys = Failed ys
193+
194+instance Alternative Result where
195+ empty = Failed mempty
196+ Passed x <|> _ = Passed x
197+ _ <|> y = y
198+
199+instance Monad Result where
200+ return = pure
201+ Passed x >>= f = f x
202+ Failed xs >>= _ = Failed xs
203+
204+-- | Validation configuration.
205+data Config = Config
206+ { -- | Pattern checker for @'_paramSchemaPattern'@ validation.
207+ configPatternChecker :: Pattern -> Text -> Bool
208+ -- | Schema definitions in scope to resolve references.
209+ , configDefinitions :: Definitions Schema
210+ }
211+
212+-- | Default @'Config'@:
213+--
214+-- @
215+-- defaultConfig = 'Config'
216+-- { 'configPatternChecker' = \\_pattern _str -> True
217+-- , 'configDefinitions' = mempty
218+-- }
219+-- @
220+defaultConfig :: Config
221+defaultConfig = Config
222+ { configPatternChecker = \_pattern _str -> True
223+ , configDefinitions = mempty
224+ }
225+
226+-- | Value validation.
227+newtype Validation s a = Validation { runValidation :: Config -> s -> Result a }
228+ deriving (Functor)
229+
230+instance Applicative (Validation schema) where
231+ pure x = Validation (\_ _ -> pure x)
232+ Validation f <*> Validation x = Validation (\c s -> f c s <*> x c s)
233+
234+instance Alternative (Validation schema) where
235+ empty = Validation (\_ _ -> empty)
236+ Validation x <|> Validation y = Validation (\c s -> x c s <|> y c s)
237+
238+instance Profunctor Validation where
239+ dimap f g (Validation k) = Validation (\c s -> fmap g (k c (f s)))
240+
241+instance Choice Validation where
242+ left' (Validation g) = Validation (\c -> either (fmap Left . g c) (pure . Right))
243+ right' (Validation g) = Validation (\c -> either (pure . Left) (fmap Right . g c))
244+
245+instance Monad (Validation s) where
246+ return = pure
247+ Validation x >>= f = Validation (\c s -> x c s >>= \y -> runValidation (f y) c s)
248+ (>>) = (*>)
249+
250+withConfig :: (Config -> Validation s a) -> Validation s a
251+withConfig f = Validation (\c -> runValidation (f c) c)
252+
253+withSchema :: (s -> Validation s a) -> Validation s a
254+withSchema f = Validation (\c s -> runValidation (f s) c s)
255+
256+-- | Issue an error message.
257+invalid :: String -> Validation schema a
258+invalid msg = Validation (\_ _ -> Failed [msg])
259+
260+-- | Validation passed.
261+valid :: Validation schema ()
262+valid = pure ()
263+
264+-- | Validate schema's property given a lens into that property
265+-- and property checker.
266+checkMissing :: Validation s () -> Lens' s (Maybe a) -> (a -> Validation s ()) -> Validation s ()
267+checkMissing missing l g = withSchema $ \sch ->
268+ case sch ^. l of
269+ Nothing -> missing
270+ Just x -> g x
271+
272+-- | Validate schema's property given a lens into that property
273+-- and property checker.
274+-- If property is missing in schema, consider it valid.
275+check :: Lens' s (Maybe a) -> (a -> Validation s ()) -> Validation s ()
276+check = checkMissing valid
277+
278+-- | Validate same value with different schema.
279+sub :: t -> Validation t a -> Validation s a
280+sub = lmap . const
281+
282+-- | Validate same value with a part of the original schema.
283+sub_ :: Getting a s a -> Validation a r -> Validation s r
284+sub_ = lmap . view
285+
286+-- | Validate value against a schema given schema reference and validation function.
287+withRef :: Reference -> (Schema -> Validation s a) -> Validation s a
288+withRef (Reference ref) f = withConfig $ \cfg ->
289+ case InsOrdHashMap.lookup ref (configDefinitions cfg) of
290+ Nothing -> invalid $ "unknown schema " ++ show ref
291+ Just s -> f s
292+
293+validateWithSchemaRef :: Referenced Schema -> Value -> Validation s ()
294+validateWithSchemaRef (Ref ref) js = withRef ref $ \sch -> sub sch (validateWithSchema js)
295+validateWithSchemaRef (Inline s) js = sub s (validateWithSchema js)
296+
297+-- | Validate JSON @'Value'@ with Swagger @'Schema'@.
298+validateWithSchema :: Value -> Validation Schema ()
299+validateWithSchema value = do
300+ validateSchemaType value
301+ sub_ paramSchema $ validateEnum value
302+
303+-- | Validate JSON @'Value'@ with Swagger @'ParamSchema'@.
304+validateWithParamSchema :: Value -> Validation (ParamSchema t) ()
305+validateWithParamSchema value = do
306+ validateParamSchemaType value
307+ validateEnum value
308+
309+validateInteger :: Scientific -> Validation (ParamSchema t) ()
310+validateInteger n = do
311+ when (not (isInteger n)) $
312+ invalid ("not an integer")
313+ validateNumber n
314+
315+validateNumber :: Scientific -> Validation (ParamSchema t) ()
316+validateNumber n = withConfig $ \_cfg -> withSchema $ \sch -> do
317+ let exMax = Just True == sch ^. exclusiveMaximum
318+ exMin = Just True == sch ^. exclusiveMinimum
319+
320+ check maximum_ $ \m ->
321+ when (if exMax then (n >= m) else (n > m)) $
322+ invalid ("value " ++ show n ++ " exceeds maximum (should be " ++ if exMax then "<" else "<=" ++ show m ++ ")")
323+
324+ check minimum_ $ \m ->
325+ when (if exMin then (n <= m) else (n < m)) $
326+ invalid ("value " ++ show n ++ " falls below minimum (should be " ++ if exMin then ">" else ">=" ++ show m ++ ")")
327+
328+ check multipleOf $ \k ->
329+ when (not (isInteger (n / k))) $
330+ invalid ("expected a multiple of " ++ show k ++ " but got " ++ show n)
331+
332+validateString :: Text -> Validation (ParamSchema t) ()
333+validateString s = do
334+ check maxLength $ \n ->
335+ when (len > fromInteger n) $
336+ invalid ("string is too long (length should be <=" ++ show n ++ ")")
337+
338+ check minLength $ \n ->
339+ when (len < fromInteger n) $
340+ invalid ("string is too short (length should be >=" ++ show n ++ ")")
341+
342+ check pattern $ \regex -> do
343+ withConfig $ \cfg -> do
344+ when (not (configPatternChecker cfg regex s)) $
345+ invalid ("string does not match pattern " ++ show regex)
346+ where
347+ len = Text.length s
348+
349+validateArray :: Vector Value -> Validation (ParamSchema t) ()
350+validateArray xs = do
351+ check maxItems $ \n ->
352+ when (len > fromInteger n) $
353+ invalid ("array exceeds maximum size (should be <=" ++ show n ++ ")")
354+
355+ check minItems $ \n ->
356+ when (len < fromInteger n) $
357+ invalid ("array is too short (size should be >=" ++ show n ++ ")")
358+
359+ check items $ \case
360+ SwaggerItemsPrimitive _ itemSchema -> sub itemSchema $ traverse_ validateWithParamSchema xs
361+ SwaggerItemsObject itemSchema -> traverse_ (validateWithSchemaRef itemSchema) xs
362+ SwaggerItemsArray itemSchemas -> do
363+ when (len /= length itemSchemas) $
364+ invalid ("array size is invalid (should be exactly " ++ show (length itemSchemas) ++ ")")
365+ sequenceA_ (zipWith validateWithSchemaRef itemSchemas (Vector.toList xs))
366+
367+ check uniqueItems $ \unique ->
368+ when (unique && not allUnique) $
369+ invalid ("array is expected to contain unique items, but it does not")
370+ where
371+ len = Vector.length xs
372+ allUnique = len == HashSet.size (HashSet.fromList (Vector.toList xs))
373+
374+validateObject :: HashMap Text Value -> Validation Schema ()
375+validateObject o = withSchema $ \sch ->
376+ case sch ^. discriminator of
377+ Just pname -> case fromJSON <$> HashMap.lookup pname o of
378+ Just (Success ref) -> validateWithSchemaRef ref (Object o)
379+ Just (Error msg) -> invalid ("failed to parse discriminator property " ++ show pname ++ ": " ++ show msg)
380+ Nothing -> invalid ("discriminator property " ++ show pname ++ "is missing")
381+ Nothing -> do
382+ check maxProperties $ \n ->
383+ when (size > n) $
384+ invalid ("object size exceeds maximum (total number of properties should be <=" ++ show n ++ ")")
385+
386+ check minProperties $ \n ->
387+ when (size < n) $
388+ invalid ("object size is too small (total number of properties should be >=" ++ show n ++ ")")
389+
390+ validateRequired
391+ validateProps
392+ where
393+ size = fromIntegral (HashMap.size o)
394+
395+ validateRequired = withSchema $ \sch -> traverse_ validateReq (sch ^. required)
396+ validateReq n =
397+ when (not (HashMap.member n o)) $
398+ invalid ("property " ++ show n ++ " is required, but not found in " ++ show (encode o))
399+
400+ validateProps = withSchema $ \sch -> do
401+ for_ (HashMap.toList o) $ \(k, v) ->
402+ case v of
403+ Null | not (k `elem` (sch ^. required)) -> valid -- null is fine for non-required property
404+ _ ->
405+ case InsOrdHashMap.lookup k (sch ^. properties) of
406+ Nothing -> checkMissing (unknownProperty k) additionalProperties $ validateAdditional k v
407+ Just s -> validateWithSchemaRef s v
408+
409+ validateAdditional _ _ (AdditionalPropertiesAllowed True) = valid
410+ validateAdditional k _ (AdditionalPropertiesAllowed False) = invalid $ "additionalProperties=false but extra property " <> show k <> " found"
411+ validateAdditional _ v (AdditionalPropertiesSchema s) = validateWithSchemaRef s v
412+
413+ unknownProperty :: Text -> Validation s a
414+ unknownProperty pname = invalid $
415+ "property " <> show pname <> " is found in JSON value, but it is not mentioned in Swagger schema"
416+
417+validateEnum :: Value -> Validation (ParamSchema t) ()
418+validateEnum value = do
419+ check enum_ $ \xs ->
420+ when (value `notElem` xs) $
421+ invalid ("expected one of " ++ show (encode xs) ++ " but got " ++ show value)
422+
423+-- | Infer schema type based on used properties.
424+--
425+-- This is like 'inferParamSchemaTypes', but also works for objects:
426+--
427+-- >>> inferSchemaTypes <$> decode "{\"minProperties\": 1}"
428+-- Just [SwaggerObject]
429+inferSchemaTypes :: Schema -> [SwaggerType 'SwaggerKindSchema]
430+inferSchemaTypes sch = inferParamSchemaTypes (sch ^. paramSchema) ++
431+ [ SwaggerObject | any ($ sch)
432+ [ has (additionalProperties._Just)
433+ , has (maxProperties._Just)
434+ , has (minProperties._Just)
435+ , has (properties.folded)
436+ , has (required.folded) ] ]
437+
438+-- | Infer schema type based on used properties.
439+--
440+-- >>> inferSchemaTypes <$> decode "{\"minLength\": 2}"
441+-- Just [SwaggerString]
442+--
443+-- >>> inferSchemaTypes <$> decode "{\"maxItems\": 0}"
444+-- Just [SwaggerArray]
445+--
446+-- From numeric properties 'SwaggerInteger' type is inferred.
447+-- If you want 'SwaggerNumber' instead, you must specify it explicitly.
448+--
449+-- >>> inferSchemaTypes <$> decode "{\"minimum\": 1}"
450+-- Just [SwaggerInteger]
451+inferParamSchemaTypes :: ParamSchema t -> [SwaggerType t]
452+inferParamSchemaTypes sch = concat
453+ [ [ SwaggerArray | any ($ sch)
454+ [ has (items._Just)
455+ , has (maxItems._Just)
456+ , has (minItems._Just)
457+ , has (uniqueItems._Just) ] ]
458+ , [ SwaggerInteger | any ($ sch)
459+ [ has (exclusiveMaximum._Just)
460+ , has (exclusiveMinimum._Just)
461+ , has (maximum_._Just)
462+ , has (minimum_._Just)
463+ , has (multipleOf._Just) ] ]
464+ , [ SwaggerString | any ($ sch)
465+ [ has (maxLength._Just)
466+ , has (minLength._Just)
467+ , has (pattern._Just) ] ]
468+ ]
469+
470+validateSchemaType :: Value -> Validation Schema ()
471+validateSchemaType value = withSchema $ \sch ->
472+ case (sch ^. type_, value) of
473+ (Just SwaggerNull, Null) -> valid
474+ (Just SwaggerBoolean, Bool _) -> valid
475+ (Just SwaggerInteger, Number n) -> sub_ paramSchema (validateInteger n)
476+ (Just SwaggerNumber, Number n) -> sub_ paramSchema (validateNumber n)
477+ (Just SwaggerString, String s) -> sub_ paramSchema (validateString s)
478+ (Just SwaggerArray, Array xs) -> sub_ paramSchema (validateArray xs)
479+ (Just SwaggerObject, Object o) -> validateObject o
480+ (Nothing, Null) -> valid
481+ (Nothing, Bool _) -> valid
482+ -- Number by default
483+ (Nothing, Number n) -> sub_ paramSchema (validateNumber n)
484+ (Nothing, String s) -> sub_ paramSchema (validateString s)
485+ (Nothing, Array xs) -> sub_ paramSchema (validateArray xs)
486+ (Nothing, Object o) -> validateObject o
487+ bad -> invalid $ "expected JSON value of type " ++ showType bad
488+
489+validateParamSchemaType :: Value -> Validation (ParamSchema t) ()
490+validateParamSchemaType value = withSchema $ \sch ->
491+ case (sch ^. type_, value) of
492+ (Just SwaggerBoolean, Bool _) -> valid
493+ (Just SwaggerInteger, Number n) -> validateInteger n
494+ (Just SwaggerNumber, Number n) -> validateNumber n
495+ (Just SwaggerString, String s) -> validateString s
496+ (Just SwaggerArray, Array xs) -> validateArray xs
497+ (Nothing, Bool _) -> valid
498+ -- Number by default
499+ (Nothing, Number n) -> validateNumber n
500+ (Nothing, String s) -> validateString s
501+ (Nothing, Array xs) -> validateArray xs
502+ bad -> invalid $ "expected JSON value of type " ++ showType bad
503+
504+showType :: (Maybe (SwaggerType t), Value) -> String
505+showType (Just type_, _) = show type_
506+showType (Nothing, Null) = "SwaggerNull"
507+showType (Nothing, Bool _) = "SwaggerBoolean"
508+showType (Nothing, Number _) = "SwaggerNumber"
509+showType (Nothing, String _) = "SwaggerString"
510+showType (Nothing, Array _) = "SwaggerArray"
511+showType (Nothing, Object _) = "SwaggerObject"
src/Data/Swagger/Internal/TypeShape.hsnew file+66
@@ -0,0 +1,66 @@
1+{-# LANGUAGE CPP #-}
2+{-# LANGUAGE ConstraintKinds #-}
3+{-# LANGUAGE DataKinds #-}
4+{-# LANGUAGE KindSignatures #-}
5+{-# LANGUAGE TypeFamilies #-}
6+{-# LANGUAGE TypeOperators #-}
7+{-# LANGUAGE UndecidableInstances #-}
8+
9+module Data.Swagger.Internal.TypeShape where
10+
11+import Data.Proxy
12+import GHC.Generics
13+import GHC.TypeLits
14+import GHC.Exts (Constraint)
15+
16+-- | Shape of a datatype.
17+data TypeShape
18+ = Enumeration -- ^ A simple enumeration.
19+ | SumOfProducts -- ^ A product or a sum of non-unit products.
20+ | Mixed -- ^ Mixed sum type with both unit and non-unit constructors.
21+
22+-- | A combined shape for a product type.
23+type family ProdCombine (a :: TypeShape) (b :: TypeShape) :: TypeShape where
24+ ProdCombine Mixed b = Mixed -- technically this cannot happen since Haskell types are sums of products
25+ ProdCombine a Mixed = Mixed -- technically this cannot happen since Haskell types are sums of products
26+ ProdCombine a b = SumOfProducts
27+
28+-- | A combined shape for a sum type.
29+type family SumCombine (a :: TypeShape) (b :: TypeShape) :: TypeShape where
30+ SumCombine Enumeration Enumeration = Enumeration
31+ SumCombine SumOfProducts SumOfProducts = SumOfProducts
32+ SumCombine a b = Mixed
33+
34+type family TypeHasSimpleShape t (f :: Symbol) :: Constraint where
35+ TypeHasSimpleShape t f = GenericHasSimpleShape t f (GenericShape (Rep t))
36+
37+type family GenericHasSimpleShape t (f :: Symbol) (s :: TypeShape) :: Constraint where
38+ GenericHasSimpleShape t f Enumeration = ()
39+ GenericHasSimpleShape t f SumOfProducts = ()
40+#if __GLASGOW_HASKELL__ < 800
41+ GenericHasSimpleShape t f Mixed = CannotDeriveSchemaForMixedSumType t
42+
43+class CannotDeriveSchemaForMixedSumType t where
44+#else
45+ GenericHasSimpleShape t f Mixed =
46+ TypeError
47+ ( Text "Cannot derive Generic-based Swagger Schema for " :<>: ShowType t
48+ :$$: ShowType t :<>: Text " is a mixed sum type (has both unit and non-unit constructors)."
49+ :$$: Text "Swagger does not have a good representation for these types."
50+ :$$: Text "Use " :<>: Text f :<>: Text " if you want to derive schema"
51+ :$$: Text "that matches aeson's Generic-based toJSON,"
52+ :$$: Text "but that's not supported by some Swagger tools."
53+ )
54+#endif
55+
56+-- | Infer a 'TypeShape' for a generic representation of a type.
57+type family GenericShape (g :: * -> *) :: TypeShape
58+
59+type instance GenericShape (f :*: g) = ProdCombine (GenericShape f) (GenericShape g)
60+type instance GenericShape (f :+: g) = SumCombine (GenericShape f) (GenericShape g)
61+type instance GenericShape (D1 d f) = GenericShape f
62+type instance GenericShape (C1 c U1) = Enumeration
63+type instance GenericShape (C1 c (S1 s f)) = SumOfProducts
64+type instance GenericShape (C1 c (f :*: g)) = SumOfProducts
65+
66+
src/Data/Swagger/Internal/Utils.hs+9−46
@@ -9,8 +9,6 @@ module Data.Swagger.Internal.Utils where
99import Prelude ()
1010import Prelude.Compat
1111
12−import Control.Arrow (first)
13−import Control.Applicative
1412import Control.Lens ((&), (%~))
1513import Control.Lens.TH
1614import Data.Aeson
@@ -20,12 +18,13 @@ import Data.Data
2018import Data.Hashable (Hashable)
2119import Data.HashMap.Strict (HashMap)
2220import qualified Data.HashMap.Strict as HashMap
21+import Data.HashMap.Strict.InsOrd (InsOrdHashMap)
22+import qualified Data.HashMap.Strict.InsOrd as InsOrdHashMap
2323import Data.Map (Map)
24−import Data.Monoid
24+import Data.Set (Set)
2525import Data.Text (Text)
2626import GHC.Generics
2727import Language.Haskell.TH (mkName)
28−import Text.Read (readMaybe)
2928
3029swaggerFieldRules :: LensRules
3130swaggerFieldRules = defaultFieldRules & lensField %~ swaggerFieldNamer
@@ -44,6 +43,7 @@ swaggerFieldRules = defaultFieldRules & lensField %~ swaggerFieldNamer
4443 fixName' "minimum" = "minimum_" -- Prelude conflict
4544 fixName' "maximum" = "maximum_" -- Prelude conflict
4645 fixName' "enum" = "enum_" -- Control.Lens conflict
46+ fixName' "head" = "head_" -- Prelude conflict
4747 fixName' n = n
4848
4949gunfoldEnum :: String -> [a] -> (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c a
@@ -51,17 +51,6 @@ gunfoldEnum tname xs _k z c = case lookup (constrIndex c) (zip [1..] xs) of
5151 Just x -> z x
5252 Nothing -> error $ "Data.Data.gunfold: Constructor " ++ show c ++ " is not of type " ++ tname ++ "."
5353
54−hashMapMapKeys :: (Eq k', Hashable k') => (k -> k') -> HashMap k v -> HashMap k' v
55−hashMapMapKeys f = HashMap.fromList . map (first f) . HashMap.toList
56−
57−hashMapTraverseKeys :: (Eq k', Hashable k', Applicative f) => (k -> f k') -> HashMap k v -> f (HashMap k' v)
58−hashMapTraverseKeys f = fmap HashMap.fromList . traverse g . HashMap.toList
59− where
60− g (x, y) = (\a -> (a, y)) <$> f x
61−
62−hashMapReadKeys :: (Eq k, Read k, Hashable k, Alternative f) => HashMap String v -> f (HashMap k v)
63−hashMapReadKeys = hashMapTraverseKeys (maybe empty pure . readMaybe)
64−
6554jsonPrefix :: String -> Options
6655jsonPrefix prefix = defaultOptions
6756 { fieldLabelModifier = modifier . drop 1
@@ -83,40 +72,10 @@ parseOneOf xs js =
8372 where
8473 ys = zip (map toJSON xs) xs
8574
86−omitEmptiesExcept :: (Text -> Value -> Bool) -> Value -> Value
87−omitEmptiesExcept f (Object o) = Object (HashMap.filterWithKey nonEmpty o)
88− where
89− nonEmpty k js = f k js || (js /= Object mempty) && (js /= Array mempty) && (js /= Null)
90−omitEmptiesExcept _ js = js
91−
92−omitEmpties :: Value -> Value
93−omitEmpties = omitEmptiesExcept (\_ _ -> False)
94−
95−genericToJSONWithSub :: (Generic a, GToJSON (Rep a)) => Text -> Options -> a -> Value
96−genericToJSONWithSub sub opts x =
97− case genericToJSON opts x of
98− Object o ->
99− case HashMap.lookup sub o of
100− Just so -> Object (HashMap.delete sub o) <+> so
101− Nothing -> Object o -- no subjson, leaving object as is
102− _ -> error "genericToJSONWithSub: subjson is not an object"
103−
104−genericParseJSONWithSub :: (Generic a, GFromJSON (Rep a)) => Text -> Options -> Value -> Parser a
105−genericParseJSONWithSub sub opts js@(Object o)
106− = genericParseJSON opts js -- try without subjson
107− <|> genericParseJSON opts js' -- try with subjson
108− where
109− js' = Object (HashMap.insert sub (Object o) o)
110−genericParseJSONWithSub _ _ _ = error "genericParseJSONWithSub: given json is not an object"
111−
11275(<+>) :: Value -> Value -> Value
11376Object x <+> Object y = Object (x <> y)
11477_ <+> _ = error "<+>: merging non-objects"
11578
116−withDefaults :: (Value -> Parser a) -> [Pair] -> Value -> Parser a
117−withDefaults parser defs js@(Object _) = parser (js <+> object defs)
118−withDefaults _ _ _ = empty
119−
12079genericMempty :: (Generic a, GMonoid (Rep a)) => a
12180genericMempty = to gmempty
12281
@@ -152,12 +111,17 @@ class SwaggerMonoid m where
152111 swaggerMappend = mappend
153112
154113instance SwaggerMonoid [a]
114+instance Ord a => SwaggerMonoid (Set a)
155115instance Ord k => SwaggerMonoid (Map k v)
156116
157117instance (Eq k, Hashable k) => SwaggerMonoid (HashMap k v) where
158118 swaggerMempty = mempty
159119 swaggerMappend = HashMap.unionWith (\_old new -> new)
160120
121+instance (Eq k, Hashable k) => SwaggerMonoid (InsOrdHashMap k v) where
122+ swaggerMempty = mempty
123+ swaggerMappend = InsOrdHashMap.unionWith (\_old new -> new)
124+
161125instance SwaggerMonoid Text where
162126 swaggerMempty = mempty
163127 swaggerMappend x "" = x
@@ -167,4 +131,3 @@ instance SwaggerMonoid (Maybe a) where
167131 swaggerMempty = Nothing
168132 swaggerMappend x Nothing = x
169133 swaggerMappend _ y = y
170−
src/Data/Swagger/Lens.hs+30−9
@@ -7,9 +7,16 @@
77{-# LANGUAGE RankNTypes #-}
88{-# LANGUAGE TemplateHaskell #-}
99{-# LANGUAGE TypeFamilies #-}
10+{-# LANGUAGE DataKinds #-}
1011{-# LANGUAGE UndecidableInstances #-}
1112{-# OPTIONS_GHC -fno-warn-orphans #-}
1213#include "overlapping-compat.h"
14+-- |
15+-- Module: Data.Swagger.Lens
16+-- Maintainer: Nickolay Kudasov <nickolay@getshoptv.com>
17+-- Stability: experimental
18+--
19+-- Lenses and prisms for Swagger.
1320module Data.Swagger.Lens where
1421
1522import Control.Lens
@@ -26,7 +33,7 @@ makeFields ''Host
2633makeFields ''Info
2734makeFields ''Contact
2835makeFields ''License
29−makeFields ''PathItem
36+makeLensesWith swaggerFieldRules ''PathItem
3037makeFields ''Tag
3138makeFields ''Operation
3239makeFields ''Param
@@ -48,22 +55,28 @@ makeFields ''ExternalDocs
4855makePrisms ''ParamAnySchema
4956-- ** 'SecuritySchemeType' prisms
5057makePrisms ''SecuritySchemeType
58+-- ** 'Referenced' prisms
59+makePrisms ''Referenced
5160
5261-- ** 'SwaggerItems' prisms
5362
54−_SwaggerItemsArray :: forall t. (t ~ Schema) => Review (SwaggerItems t) [Referenced Schema]
63+_SwaggerItemsArray :: Review (SwaggerItems 'SwaggerKindSchema) [Referenced Schema]
5564_SwaggerItemsArray
56− = prism (\x -> SwaggerItemsArray x) $ \x -> case x of
65+ = unto (\x -> SwaggerItemsArray x)
66+{- \x -> case x of
5767 SwaggerItemsPrimitive c p -> Left (SwaggerItemsPrimitive c p)
5868 SwaggerItemsObject o -> Left (SwaggerItemsObject o)
5969 SwaggerItemsArray a -> Right a
70+-}
6071
61−_SwaggerItemsObject :: forall t. (t ~ Schema) => Review (SwaggerItems t) (Referenced Schema)
72+_SwaggerItemsObject :: Review (SwaggerItems 'SwaggerKindSchema) (Referenced Schema)
6273_SwaggerItemsObject
63− = prism (\x -> SwaggerItemsObject x) $ \x -> case x of
74+ = unto (\x -> SwaggerItemsObject x)
75+{- \x -> case x of
6476 SwaggerItemsPrimitive c p -> Left (SwaggerItemsPrimitive c p)
6577 SwaggerItemsObject o -> Right o
6678 SwaggerItemsArray a -> Left (SwaggerItemsArray a)
79+-}
6780
6881_SwaggerItemsPrimitive :: forall t p f. (Profunctor p, Bifunctor p, Functor f) => Optic' p f (SwaggerItems t) (Maybe (CollectionFormat t), ParamSchema t)
6982_SwaggerItemsPrimitive = unto (\(c, p) -> SwaggerItemsPrimitive c p)
@@ -83,11 +96,19 @@ instance At Responses where at n = responses . at n
8396instance Ixed Operation where ix n = responses . ix n
8497instance At Operation where at n = responses . at n
8598
99+type instance Index SecurityDefinitions = Text
100+type instance IxValue SecurityDefinitions = SecurityScheme
101+
102+instance Ixed SecurityDefinitions where ix n = (coerced :: Lens' SecurityDefinitions (Definitions SecurityScheme)). ix n
103+instance At SecurityDefinitions where at n = (coerced :: Lens' SecurityDefinitions (Definitions SecurityScheme)). at n
104+
105+instance HasParamSchema NamedSchema (ParamSchema 'SwaggerKindSchema) where paramSchema = schema.paramSchema
106+
86107-- HasType instances
87−instance HasType Header (SwaggerType Header) where type_ = paramSchema.type_
88−instance HasType Schema (SwaggerType Schema) where type_ = paramSchema.type_
89−instance HasType NamedSchema (SwaggerType Schema) where type_ = schema.paramSchema.type_
90−instance HasType ParamOtherSchema (SwaggerType ParamOtherSchema) where type_ = paramSchema.type_
108+instance HasType Header (Maybe (SwaggerType ('SwaggerKindNormal Header))) where type_ = paramSchema.type_
109+instance HasType Schema (Maybe (SwaggerType 'SwaggerKindSchema)) where type_ = paramSchema.type_
110+instance HasType NamedSchema (Maybe (SwaggerType 'SwaggerKindSchema)) where type_ = paramSchema.type_
111+instance HasType ParamOtherSchema (Maybe (SwaggerType 'SwaggerKindParamOtherSchema)) where type_ = paramSchema.type_
91112
92113-- HasDefault instances
93114instance HasDefault Header (Maybe Value) where default_ = paramSchema.default_
src/Data/Swagger/Operation.hsnew file+193
@@ -0,0 +1,193 @@
1+{-# LANGUAGE RankNTypes #-}
2+-- |
3+-- Module: Data.Swagger.Operation
4+-- Maintainer: Nickolay Kudasov <nickolay@getshoptv.com>
5+-- Stability: experimental
6+--
7+-- Helper traversals and functions for Swagger operations manipulations.
8+-- These might be useful when you already have Swagger specification
9+-- generated by something else.
10+module Data.Swagger.Operation (
11+ -- * Operation traversals
12+ allOperations,
13+ operationsOf,
14+
15+ -- * Manipulation
16+ -- ** Tags
17+ applyTags,
18+ applyTagsFor,
19+
20+ -- ** Responses
21+ setResponse,
22+ setResponseWith,
23+ setResponseFor,
24+ setResponseForWith,
25+
26+ -- ** Paths
27+ prependPath,
28+
29+ -- * Miscellaneous
30+ declareResponse,
31+) where
32+
33+import Prelude ()
34+import Prelude.Compat
35+
36+import Control.Lens
37+import Data.Data.Lens
38+import Data.List.Compat
39+import Data.Maybe (mapMaybe)
40+import Data.Proxy
41+import qualified Data.Set as Set
42+
43+import Data.Swagger.Declare
44+import Data.Swagger.Internal
45+import Data.Swagger.Lens
46+import Data.Swagger.Schema
47+
48+import qualified Data.HashMap.Strict.InsOrd as InsOrdHashMap
49+import qualified Data.HashSet.InsOrd as InsOrdHS
50+
51+-- $setup
52+-- >>> import Data.Aeson
53+-- >>> import Data.Proxy
54+-- >>> import Data.Time
55+
56+-- | Prepend path piece to all operations of the spec.
57+-- Leading and trailing slashes are trimmed/added automatically.
58+--
59+-- >>> let api = (mempty :: Swagger) & paths .~ [("/info", mempty)]
60+-- >>> encode $ prependPath "user/{user_id}" api ^. paths
61+-- "{\"/user/{user_id}/info\":{}}"
62+prependPath :: FilePath -> Swagger -> Swagger
63+prependPath path = paths %~ InsOrdHashMap.mapKeys (path </>)
64+ where
65+ x </> y = case trim y of
66+ "" -> "/" <> trim x
67+ y' -> "/" <> trim x <> "/" <> y'
68+
69+ trim = dropWhile (== '/') . dropWhileEnd (== '/')
70+
71+-- | All operations of a Swagger spec.
72+allOperations :: Traversal' Swagger Operation
73+allOperations = paths.traverse.template
74+
75+-- | @'operationsOf' sub@ will traverse only those operations
76+-- that are present in @sub@. Note that @'Operation'@ is determined
77+-- by both path and method.
78+--
79+-- >>> let ok = (mempty :: Operation) & at 200 ?~ "OK"
80+-- >>> let api = (mempty :: Swagger) & paths .~ [("/user", mempty & get ?~ ok & post ?~ ok)]
81+-- >>> let sub = (mempty :: Swagger) & paths .~ [("/user", mempty & get ?~ mempty)]
82+-- >>> encode api
83+-- "{\"swagger\":\"2.0\",\"info\":{\"version\":\"\",\"title\":\"\"},\"paths\":{\"/user\":{\"get\":{\"responses\":{\"200\":{\"description\":\"OK\"}}},\"post\":{\"responses\":{\"200\":{\"description\":\"OK\"}}}}}}"
84+-- >>> encode $ api & operationsOf sub . at 404 ?~ "Not found"
85+-- "{\"swagger\":\"2.0\",\"info\":{\"version\":\"\",\"title\":\"\"},\"paths\":{\"/user\":{\"get\":{\"responses\":{\"404\":{\"description\":\"Not found\"},\"200\":{\"description\":\"OK\"}}},\"post\":{\"responses\":{\"200\":{\"description\":\"OK\"}}}}}}"
86+operationsOf :: Swagger -> Traversal' Swagger Operation
87+operationsOf sub = paths.itraversed.withIndex.subops
88+ where
89+ -- | Traverse operations that correspond to paths and methods of the sub API.
90+ subops :: Traversal' (FilePath, PathItem) Operation
91+ subops f (path, item) = case InsOrdHashMap.lookup path (sub ^. paths) of
92+ Just subitem -> (,) path <$> methodsOf subitem f item
93+ Nothing -> pure (path, item)
94+
95+ -- | Traverse operations that exist in a given @'PathItem'@
96+ -- This is used to traverse only the operations that exist in sub API.
97+ methodsOf :: PathItem -> Traversal' PathItem Operation
98+ methodsOf pathItem = partsOf template . itraversed . indices (`elem` ns) . _Just
99+ where
100+ ops = pathItem ^.. template :: [Maybe Operation]
101+ ns = mapMaybe (fmap fst . sequenceA) $ zip [0..] ops
102+
103+-- | Apply tags to all operations and update the global list of tags.
104+--
105+-- @
106+-- 'applyTags' = 'applyTagsFor' 'allOperations'
107+-- @
108+applyTags :: [Tag] -> Swagger -> Swagger
109+applyTags = applyTagsFor allOperations
110+
111+-- | Apply tags to a part of Swagger spec and update the global
112+-- list of tags.
113+applyTagsFor :: Traversal' Swagger Operation -> [Tag] -> Swagger -> Swagger
114+applyTagsFor ops ts swag = swag
115+ & ops . tags %~ (<> InsOrdHS.fromList (map _tagName ts))
116+ & tags %~ (<> InsOrdHS.fromList ts)
117+
118+-- | Construct a response with @'Schema'@ while declaring all
119+-- necessary schema definitions.
120+--
121+-- >>> encode $ runDeclare (declareResponse (Proxy :: Proxy Day)) mempty
122+-- "[{\"Day\":{\"example\":\"2016-07-22\",\"format\":\"date\",\"type\":\"string\"}},{\"description\":\"\",\"schema\":{\"$ref\":\"#/definitions/Day\"}}]"
123+declareResponse :: ToSchema a => Proxy a -> Declare (Definitions Schema) Response
124+declareResponse proxy = do
125+ s <- declareSchemaRef proxy
126+ return (mempty & schema ?~ s)
127+
128+-- | Set response for all operations.
129+-- This will also update global schema definitions.
130+--
131+-- If the response already exists it will be overwritten.
132+--
133+-- @
134+-- 'setResponse' = 'setResponseFor' 'allOperations'
135+-- @
136+--
137+-- Example:
138+--
139+-- >>> let api = (mempty :: Swagger) & paths .~ [("/user", mempty & get ?~ mempty)]
140+-- >>> let res = declareResponse (Proxy :: Proxy Day)
141+-- >>> encode $ api & setResponse 200 res
142+-- "{\"swagger\":\"2.0\",\"info\":{\"version\":\"\",\"title\":\"\"},\"paths\":{\"/user\":{\"get\":{\"responses\":{\"200\":{\"schema\":{\"$ref\":\"#/definitions/Day\"},\"description\":\"\"}}}}},\"definitions\":{\"Day\":{\"example\":\"2016-07-22\",\"format\":\"date\",\"type\":\"string\"}}}"
143+--
144+-- See also @'setResponseWith'@.
145+setResponse :: HttpStatusCode -> Declare (Definitions Schema) Response -> Swagger -> Swagger
146+setResponse = setResponseFor allOperations
147+
148+-- | Set or update response for all operations.
149+-- This will also update global schema definitions.
150+--
151+-- If the response already exists, but it can't be dereferenced (invalid @\$ref@),
152+-- then just the new response is used.
153+--
154+-- @
155+-- 'setResponseWith' = 'setResponseForWith' 'allOperations'
156+-- @
157+--
158+-- See also @'setResponse'@.
159+setResponseWith :: (Response -> Response -> Response) -> HttpStatusCode -> Declare (Definitions Schema) Response -> Swagger -> Swagger
160+setResponseWith = setResponseForWith allOperations
161+
162+-- | Set response for specified operations.
163+-- This will also update global schema definitions.
164+--
165+-- If the response already exists it will be overwritten.
166+--
167+-- See also @'setResponseForWith'@.
168+setResponseFor :: Traversal' Swagger Operation -> HttpStatusCode -> Declare (Definitions Schema) Response -> Swagger -> Swagger
169+setResponseFor ops code dres swag = swag
170+ & definitions %~ (<> defs)
171+ & ops . at code ?~ Inline res
172+ where
173+ (defs, res) = runDeclare dres mempty
174+
175+-- | Set or update response for specified operations.
176+-- This will also update global schema definitions.
177+--
178+-- If the response already exists, but it can't be dereferenced (invalid @\$ref@),
179+-- then just the new response is used.
180+--
181+-- See also @'setResponseFor'@.
182+setResponseForWith :: Traversal' Swagger Operation -> (Response -> Response -> Response) -> HttpStatusCode -> Declare (Definitions Schema) Response -> Swagger -> Swagger
183+setResponseForWith ops f code dres swag = swag
184+ & definitions %~ (<> defs)
185+ & ops . at code %~ Just . Inline . combine
186+ where
187+ (defs, new) = runDeclare dres mempty
188+
189+ combine (Just (Ref (Reference n))) = case swag ^. responses.at n of
190+ Just old -> f old new
191+ Nothing -> new -- response name can't be dereferenced, replacing with new response
192+ combine (Just (Inline old)) = f old new
193+ combine Nothing = new
src/Data/Swagger/Optics.hsnew file+597
@@ -0,0 +1,597 @@
1+{-# LANGUAGE DataKinds #-}
2+{-# LANGUAGE FlexibleInstances #-}
3+{-# LANGUAGE MultiParamTypeClasses #-}
4+{-# LANGUAGE OverloadedLabels #-}
5+{-# LANGUAGE TemplateHaskell #-}
6+{-# LANGUAGE TypeFamilies #-}
7+{-# LANGUAGE UndecidableInstances #-}
8+{-# OPTIONS_GHC -fno-warn-orphans #-}
9+-- |
10+-- Module: Data.Swagger.Optics
11+-- Maintainer: Andrzej Rybczak <andrzej@rybczak.net>
12+-- Stability: experimental
13+--
14+-- Lenses and prisms for the <https://hackage.haskell.org/package/optics optics>
15+-- library.
16+--
17+-- >>> import Data.Aeson
18+-- >>> import Optics.Core
19+-- >>> :set -XOverloadedLabels
20+--
21+-- Example from the "Data.Swagger" module using @optics@:
22+--
23+-- >>> :{
24+-- encode $ (mempty :: Swagger)
25+-- & #definitions .~ [ ("User", mempty & #type ?~ SwaggerString) ]
26+-- & #paths .~
27+-- [ ("/user", mempty & #get ?~ (mempty
28+-- & #produces ?~ MimeList ["application/json"]
29+-- & at 200 ?~ ("OK" & #_Inline % #schema ?~ Ref (Reference "User"))
30+-- & at 404 ?~ "User info not found")) ]
31+-- :}
32+-- "{\"swagger\":\"2.0\",\"info\":{\"version\":\"\",\"title\":\"\"},\"paths\":{\"/user\":{\"get\":{\"produces\":[\"application/json\"],\"responses\":{\"404\":{\"description\":\"User info not found\"},\"200\":{\"schema\":{\"$ref\":\"#/definitions/User\"},\"description\":\"OK\"}}}}},\"definitions\":{\"User\":{\"type\":\"string\"}}}"
33+--
34+-- For convenience optics are defined as /labels/. It means that field accessor
35+-- names can be overloaded for different types. One such common field is
36+-- @#description@. Many components of a Swagger specification can have
37+-- descriptions, and you can use the same name for them:
38+--
39+-- >>> encode $ (mempty :: Response) & #description .~ "No content"
40+-- "{\"description\":\"No content\"}"
41+-- >>> :{
42+-- encode $ (mempty :: Schema)
43+-- & #type ?~ SwaggerBoolean
44+-- & #description ?~ "To be or not to be"
45+-- :}
46+-- "{\"description\":\"To be or not to be\",\"type\":\"boolean\"}"
47+--
48+-- @'ParamSchema'@ is basically the /base schema specification/ and many types
49+-- contain it. So for convenience, all @'ParamSchema'@ fields are transitively
50+-- made fields of the type that has it. For example, you can use @#type@ to
51+-- access @'SwaggerType'@ of @'Header'@ schema without having to use
52+-- @#paramSchema@:
53+--
54+-- >>> encode $ (mempty :: Header) & #type ?~ SwaggerNumber
55+-- "{\"type\":\"number\"}"
56+--
57+-- Additionally, to simplify working with @'Response'@, both @'Operation'@ and
58+-- @'Responses'@ have direct access to it via @'Optics.Core.At.at'@. Example:
59+--
60+-- >>> :{
61+-- encode $ (mempty :: Operation)
62+-- & at 404 ?~ "Not found"
63+-- :}
64+-- "{\"responses\":{\"404\":{\"description\":\"Not found\"}}}"
65+--
66+module Data.Swagger.Optics () where
67+
68+import Data.Aeson (Value)
69+import Data.Scientific (Scientific)
70+import Data.Swagger.Internal
71+import Data.Text (Text)
72+import Optics.Core
73+import Optics.TH
74+
75+-- Lenses
76+
77+makeFieldLabels ''Swagger
78+makeFieldLabels ''Host
79+makeFieldLabels ''Info
80+makeFieldLabels ''Contact
81+makeFieldLabels ''License
82+makeFieldLabels ''PathItem
83+makeFieldLabels ''Tag
84+makeFieldLabels ''Operation
85+makeFieldLabels ''Param
86+makeFieldLabels ''ParamOtherSchema
87+makeFieldLabels ''Header
88+makeFieldLabels ''Schema
89+makeFieldLabels ''NamedSchema
90+makeFieldLabels ''ParamSchema
91+makeFieldLabels ''Xml
92+makeFieldLabels ''Responses
93+makeFieldLabels ''Response
94+makeFieldLabels ''SecurityScheme
95+makeFieldLabels ''ApiKeyParams
96+makeFieldLabels ''OAuth2Params
97+makeFieldLabels ''ExternalDocs
98+
99+-- Prisms
100+
101+makePrismLabels ''ParamAnySchema
102+makePrismLabels ''SecuritySchemeType
103+makePrismLabels ''Referenced
104+
105+-- SwaggerItems prisms
106+
107+instance
108+ ( a ~ [Referenced Schema]
109+ , b ~ [Referenced Schema]
110+ ) => LabelOptic "_SwaggerItemsArray"
111+ A_Review
112+ (SwaggerItems 'SwaggerKindSchema)
113+ (SwaggerItems 'SwaggerKindSchema)
114+ a
115+ b where
116+ labelOptic = unto (\x -> SwaggerItemsArray x)
117+ {-# INLINE labelOptic #-}
118+
119+instance
120+ ( a ~ Referenced Schema
121+ , b ~ Referenced Schema
122+ ) => LabelOptic "_SwaggerItemsObject"
123+ A_Review
124+ (SwaggerItems 'SwaggerKindSchema)
125+ (SwaggerItems 'SwaggerKindSchema)
126+ a
127+ b where
128+ labelOptic = unto (\x -> SwaggerItemsObject x)
129+ {-# INLINE labelOptic #-}
130+
131+instance
132+ ( a ~ (Maybe (CollectionFormat t), ParamSchema t)
133+ , b ~ (Maybe (CollectionFormat t), ParamSchema t)
134+ ) => LabelOptic "_SwaggerItemsPrimitive"
135+ A_Review
136+ (SwaggerItems t)
137+ (SwaggerItems t)
138+ a
139+ b where
140+ labelOptic = unto (\(c, p) -> SwaggerItemsPrimitive c p)
141+ {-# INLINE labelOptic #-}
142+
143+-- =============================================================
144+-- More helpful instances for easier access to schema properties
145+
146+type instance Index Responses = HttpStatusCode
147+type instance Index Operation = HttpStatusCode
148+
149+type instance IxValue Responses = Referenced Response
150+type instance IxValue Operation = Referenced Response
151+
152+instance Ixed Responses where
153+ ix n = #responses % ix n
154+ {-# INLINE ix #-}
155+instance At Responses where
156+ at n = #responses % at n
157+ {-# INLINE at #-}
158+
159+instance Ixed Operation where
160+ ix n = #responses % ix n
161+ {-# INLINE ix #-}
162+instance At Operation where
163+ at n = #responses % at n
164+ {-# INLINE at #-}
165+
166+-- #paramSchema
167+
168+instance
169+ ( a ~ ParamSchema 'SwaggerKindSchema
170+ , b ~ ParamSchema 'SwaggerKindSchema
171+ ) => LabelOptic "paramSchema" A_Lens NamedSchema NamedSchema a b where
172+ labelOptic = #schema % #paramSchema
173+ {-# INLINE labelOptic #-}
174+
175+-- #type
176+
177+instance
178+ ( a ~ Maybe (SwaggerType ('SwaggerKindNormal Header))
179+ , b ~ Maybe (SwaggerType ('SwaggerKindNormal Header))
180+ ) => LabelOptic "type" A_Lens Header Header a b where
181+ labelOptic = #paramSchema % #type
182+ {-# INLINE labelOptic #-}
183+
184+instance
185+ ( a ~ Maybe (SwaggerType 'SwaggerKindSchema)
186+ , b ~ Maybe (SwaggerType 'SwaggerKindSchema)
187+ ) => LabelOptic "type" A_Lens Schema Schema a b where
188+ labelOptic = #paramSchema % #type
189+ {-# INLINE labelOptic #-}
190+
191+instance
192+ ( a ~ Maybe (SwaggerType 'SwaggerKindSchema)
193+ , b ~ Maybe (SwaggerType 'SwaggerKindSchema)
194+ ) => LabelOptic "type" A_Lens NamedSchema NamedSchema a b where
195+ labelOptic = #paramSchema % #type
196+ {-# INLINE labelOptic #-}
197+
198+instance
199+ ( a ~ Maybe (SwaggerType 'SwaggerKindParamOtherSchema)
200+ , b ~ Maybe (SwaggerType 'SwaggerKindParamOtherSchema)
201+ ) => LabelOptic "type" A_Lens ParamOtherSchema ParamOtherSchema a b where
202+ labelOptic = #paramSchema % #type
203+ {-# INLINE labelOptic #-}
204+
205+-- #default
206+
207+instance
208+ ( a ~ Maybe Value, b ~ Maybe Value
209+ ) => LabelOptic "default" A_Lens Header Header a b where
210+ labelOptic = #paramSchema % #default
211+ {-# INLINE labelOptic #-}
212+
213+instance
214+ ( a ~ Maybe Value, b ~ Maybe Value
215+ ) => LabelOptic "default" A_Lens Schema Schema a b where
216+ labelOptic = #paramSchema % #default
217+ {-# INLINE labelOptic #-}
218+
219+instance
220+ ( a ~ Maybe Value, b ~ Maybe Value
221+ ) => LabelOptic "default" A_Lens NamedSchema NamedSchema a b where
222+ labelOptic = #paramSchema % #default
223+ {-# INLINE labelOptic #-}
224+
225+instance
226+ ( a ~ Maybe Value, b ~ Maybe Value
227+ ) => LabelOptic "default" A_Lens ParamOtherSchema ParamOtherSchema a b where
228+ labelOptic = #paramSchema % #default
229+ {-# INLINE labelOptic #-}
230+
231+-- #format
232+
233+instance
234+ ( a ~ Maybe Format, b ~ Maybe Format
235+ ) => LabelOptic "format" A_Lens Header Header a b where
236+ labelOptic = #paramSchema % #format
237+ {-# INLINE labelOptic #-}
238+
239+instance
240+ ( a ~ Maybe Format, b ~ Maybe Format
241+ ) => LabelOptic "format" A_Lens Schema Schema a b where
242+ labelOptic = #paramSchema % #format
243+ {-# INLINE labelOptic #-}
244+
245+instance
246+ ( a ~ Maybe Format, b ~ Maybe Format
247+ ) => LabelOptic "format" A_Lens NamedSchema NamedSchema a b where
248+ labelOptic = #paramSchema % #format
249+ {-# INLINE labelOptic #-}
250+
251+instance
252+ ( a ~ Maybe Format, b ~ Maybe Format
253+ ) => LabelOptic "format" A_Lens ParamOtherSchema ParamOtherSchema a b where
254+ labelOptic = #paramSchema % #format
255+ {-# INLINE labelOptic #-}
256+
257+-- #items
258+
259+instance
260+ ( a ~ Maybe (SwaggerItems ('SwaggerKindNormal Header))
261+ , b ~ Maybe (SwaggerItems ('SwaggerKindNormal Header))
262+ ) => LabelOptic "items" A_Lens Header Header a b where
263+ labelOptic = #paramSchema % #items
264+ {-# INLINE labelOptic #-}
265+
266+instance
267+ ( a ~ Maybe (SwaggerItems 'SwaggerKindSchema)
268+ , b ~ Maybe (SwaggerItems 'SwaggerKindSchema)
269+ ) => LabelOptic "items" A_Lens Schema Schema a b where
270+ labelOptic = #paramSchema % #items
271+ {-# INLINE labelOptic #-}
272+
273+instance
274+ ( a ~ Maybe (SwaggerItems 'SwaggerKindSchema)
275+ , b ~ Maybe (SwaggerItems 'SwaggerKindSchema)
276+ ) => LabelOptic "items" A_Lens NamedSchema NamedSchema a b where
277+ labelOptic = #paramSchema % #items
278+ {-# INLINE labelOptic #-}
279+
280+instance
281+ ( a ~ Maybe (SwaggerItems 'SwaggerKindParamOtherSchema)
282+ , b ~ Maybe (SwaggerItems 'SwaggerKindParamOtherSchema)
283+ ) => LabelOptic "items" A_Lens ParamOtherSchema ParamOtherSchema a b where
284+ labelOptic = #paramSchema % #items
285+ {-# INLINE labelOptic #-}
286+
287+-- #maximum
288+
289+instance
290+ ( a ~ Maybe Scientific, b ~ Maybe Scientific
291+ ) => LabelOptic "maximum" A_Lens Header Header a b where
292+ labelOptic = #paramSchema % #maximum
293+ {-# INLINE labelOptic #-}
294+
295+instance
296+ ( a ~ Maybe Scientific, b ~ Maybe Scientific
297+ ) => LabelOptic "maximum" A_Lens Schema Schema a b where
298+ labelOptic = #paramSchema % #maximum
299+ {-# INLINE labelOptic #-}
300+
301+instance
302+ ( a ~ Maybe Scientific, b ~ Maybe Scientific
303+ ) => LabelOptic "maximum" A_Lens NamedSchema NamedSchema a b where
304+ labelOptic = #paramSchema % #maximum
305+ {-# INLINE labelOptic #-}
306+
307+instance
308+ ( a ~ Maybe Scientific, b ~ Maybe Scientific
309+ ) => LabelOptic "maximum" A_Lens ParamOtherSchema ParamOtherSchema a b where
310+ labelOptic = #paramSchema % #maximum
311+ {-# INLINE labelOptic #-}
312+
313+-- #exclusiveMaximum
314+
315+instance
316+ ( a ~ Maybe Bool, b ~ Maybe Bool
317+ ) => LabelOptic "exclusiveMaximum" A_Lens Header Header a b where
318+ labelOptic = #paramSchema % #exclusiveMaximum
319+ {-# INLINE labelOptic #-}
320+
321+instance
322+ ( a ~ Maybe Bool, b ~ Maybe Bool
323+ ) => LabelOptic "exclusiveMaximum" A_Lens Schema Schema a b where
324+ labelOptic = #paramSchema % #exclusiveMaximum
325+ {-# INLINE labelOptic #-}
326+
327+instance
328+ ( a ~ Maybe Bool, b ~ Maybe Bool
329+ ) => LabelOptic "exclusiveMaximum" A_Lens NamedSchema NamedSchema a b where
330+ labelOptic = #paramSchema % #exclusiveMaximum
331+ {-# INLINE labelOptic #-}
332+
333+instance
334+ ( a ~ Maybe Bool, b ~ Maybe Bool
335+ ) => LabelOptic "exclusiveMaximum" A_Lens ParamOtherSchema ParamOtherSchema a b where
336+ labelOptic = #paramSchema % #exclusiveMaximum
337+ {-# INLINE labelOptic #-}
338+
339+-- #minimum
340+
341+instance
342+ ( a ~ Maybe Scientific, b ~ Maybe Scientific
343+ ) => LabelOptic "minimum" A_Lens Header Header a b where
344+ labelOptic = #paramSchema % #minimum
345+ {-# INLINE labelOptic #-}
346+
347+instance
348+ ( a ~ Maybe Scientific, b ~ Maybe Scientific
349+ ) => LabelOptic "minimum" A_Lens Schema Schema a b where
350+ labelOptic = #paramSchema % #minimum
351+ {-# INLINE labelOptic #-}
352+
353+instance
354+ ( a ~ Maybe Scientific, b ~ Maybe Scientific
355+ ) => LabelOptic "minimum" A_Lens NamedSchema NamedSchema a b where
356+ labelOptic = #paramSchema % #minimum
357+ {-# INLINE labelOptic #-}
358+
359+instance
360+ ( a ~ Maybe Scientific, b ~ Maybe Scientific
361+ ) => LabelOptic "minimum" A_Lens ParamOtherSchema ParamOtherSchema a b where
362+ labelOptic = #paramSchema % #minimum
363+ {-# INLINE labelOptic #-}
364+
365+-- #exclusiveMinimum
366+
367+instance
368+ ( a ~ Maybe Bool, b ~ Maybe Bool
369+ ) => LabelOptic "exclusiveMinimum" A_Lens Header Header a b where
370+ labelOptic = #paramSchema % #exclusiveMinimum
371+ {-# INLINE labelOptic #-}
372+
373+instance
374+ ( a ~ Maybe Bool, b ~ Maybe Bool
375+ ) => LabelOptic "exclusiveMinimum" A_Lens Schema Schema a b where
376+ labelOptic = #paramSchema % #exclusiveMinimum
377+ {-# INLINE labelOptic #-}
378+
379+instance
380+ ( a ~ Maybe Bool, b ~ Maybe Bool
381+ ) => LabelOptic "exclusiveMinimum" A_Lens NamedSchema NamedSchema a b where
382+ labelOptic = #paramSchema % #exclusiveMinimum
383+ {-# INLINE labelOptic #-}
384+
385+instance
386+ ( a ~ Maybe Bool, b ~ Maybe Bool
387+ ) => LabelOptic "exclusiveMinimum" A_Lens ParamOtherSchema ParamOtherSchema a b where
388+ labelOptic = #paramSchema % #exclusiveMinimum
389+ {-# INLINE labelOptic #-}
390+
391+-- #maxLength
392+
393+instance
394+ ( a ~ Maybe Integer, b ~ Maybe Integer
395+ ) => LabelOptic "maxLength" A_Lens Header Header a b where
396+ labelOptic = #paramSchema % #maxLength
397+ {-# INLINE labelOptic #-}
398+
399+instance
400+ ( a ~ Maybe Integer, b ~ Maybe Integer
401+ ) => LabelOptic "maxLength" A_Lens Schema Schema a b where
402+ labelOptic = #paramSchema % #maxLength
403+ {-# INLINE labelOptic #-}
404+
405+instance
406+ ( a ~ Maybe Integer, b ~ Maybe Integer
407+ ) => LabelOptic "maxLength" A_Lens NamedSchema NamedSchema a b where
408+ labelOptic = #paramSchema % #maxLength
409+ {-# INLINE labelOptic #-}
410+
411+instance
412+ ( a ~ Maybe Integer, b ~ Maybe Integer
413+ ) => LabelOptic "maxLength" A_Lens ParamOtherSchema ParamOtherSchema a b where
414+ labelOptic = #paramSchema % #maxLength
415+ {-# INLINE labelOptic #-}
416+
417+-- #minLength
418+
419+instance
420+ ( a ~ Maybe Integer, b ~ Maybe Integer
421+ ) => LabelOptic "minLength" A_Lens Header Header a b where
422+ labelOptic = #paramSchema % #minLength
423+ {-# INLINE labelOptic #-}
424+
425+instance
426+ ( a ~ Maybe Integer, b ~ Maybe Integer
427+ ) => LabelOptic "minLength" A_Lens Schema Schema a b where
428+ labelOptic = #paramSchema % #minLength
429+ {-# INLINE labelOptic #-}
430+
431+instance
432+ ( a ~ Maybe Integer, b ~ Maybe Integer
433+ ) => LabelOptic "minLength" A_Lens NamedSchema NamedSchema a b where
434+ labelOptic = #paramSchema % #minLength
435+ {-# INLINE labelOptic #-}
436+
437+instance
438+ ( a ~ Maybe Integer, b ~ Maybe Integer
439+ ) => LabelOptic "minLength" A_Lens ParamOtherSchema ParamOtherSchema a b where
440+ labelOptic = #paramSchema % #minLength
441+ {-# INLINE labelOptic #-}
442+
443+-- #pattern
444+
445+instance
446+ ( a ~ Maybe Text, b ~ Maybe Text
447+ ) => LabelOptic "pattern" A_Lens Header Header a b where
448+ labelOptic = #paramSchema % #pattern
449+ {-# INLINE labelOptic #-}
450+
451+instance
452+ ( a ~ Maybe Text, b ~ Maybe Text
453+ ) => LabelOptic "pattern" A_Lens Schema Schema a b where
454+ labelOptic = #paramSchema % #pattern
455+ {-# INLINE labelOptic #-}
456+
457+instance
458+ ( a ~ Maybe Text, b ~ Maybe Text
459+ ) => LabelOptic "pattern" A_Lens NamedSchema NamedSchema a b where
460+ labelOptic = #paramSchema % #pattern
461+ {-# INLINE labelOptic #-}
462+
463+instance
464+ ( a ~ Maybe Text, b ~ Maybe Text
465+ ) => LabelOptic "pattern" A_Lens ParamOtherSchema ParamOtherSchema a b where
466+ labelOptic = #paramSchema % #pattern
467+ {-# INLINE labelOptic #-}
468+
469+-- #maxItems
470+
471+instance
472+ ( a ~ Maybe Integer, b ~ Maybe Integer
473+ ) => LabelOptic "maxItems" A_Lens Header Header a b where
474+ labelOptic = #paramSchema % #maxItems
475+ {-# INLINE labelOptic #-}
476+
477+instance
478+ ( a ~ Maybe Integer, b ~ Maybe Integer
479+ ) => LabelOptic "maxItems" A_Lens Schema Schema a b where
480+ labelOptic = #paramSchema % #maxItems
481+ {-# INLINE labelOptic #-}
482+
483+instance
484+ ( a ~ Maybe Integer, b ~ Maybe Integer
485+ ) => LabelOptic "maxItems" A_Lens NamedSchema NamedSchema a b where
486+ labelOptic = #paramSchema % #maxItems
487+ {-# INLINE labelOptic #-}
488+
489+instance
490+ ( a ~ Maybe Integer, b ~ Maybe Integer
491+ ) => LabelOptic "maxItems" A_Lens ParamOtherSchema ParamOtherSchema a b where
492+ labelOptic = #paramSchema % #maxItems
493+ {-# INLINE labelOptic #-}
494+
495+-- #minItems
496+
497+instance
498+ ( a ~ Maybe Integer, b ~ Maybe Integer
499+ ) => LabelOptic "minItems" A_Lens Header Header a b where
500+ labelOptic = #paramSchema % #minItems
501+ {-# INLINE labelOptic #-}
502+
503+instance
504+ ( a ~ Maybe Integer, b ~ Maybe Integer
505+ ) => LabelOptic "minItems" A_Lens Schema Schema a b where
506+ labelOptic = #paramSchema % #minItems
507+ {-# INLINE labelOptic #-}
508+
509+instance
510+ ( a ~ Maybe Integer, b ~ Maybe Integer
511+ ) => LabelOptic "minItems" A_Lens NamedSchema NamedSchema a b where
512+ labelOptic = #paramSchema % #minItems
513+ {-# INLINE labelOptic #-}
514+
515+instance
516+ ( a ~ Maybe Integer, b ~ Maybe Integer
517+ ) => LabelOptic "minItems" A_Lens ParamOtherSchema ParamOtherSchema a b where
518+ labelOptic = #paramSchema % #minItems
519+ {-# INLINE labelOptic #-}
520+
521+-- #uniqueItems
522+
523+instance
524+ ( a ~ Maybe Bool, b ~ Maybe Bool
525+ ) => LabelOptic "uniqueItems" A_Lens Header Header a b where
526+ labelOptic = #paramSchema % #uniqueItems
527+ {-# INLINE labelOptic #-}
528+
529+instance
530+ ( a ~ Maybe Bool, b ~ Maybe Bool
531+ ) => LabelOptic "uniqueItems" A_Lens Schema Schema a b where
532+ labelOptic = #paramSchema % #uniqueItems
533+ {-# INLINE labelOptic #-}
534+
535+instance
536+ ( a ~ Maybe Bool, b ~ Maybe Bool
537+ ) => LabelOptic "uniqueItems" A_Lens NamedSchema NamedSchema a b where
538+ labelOptic = #paramSchema % #uniqueItems
539+ {-# INLINE labelOptic #-}
540+
541+instance
542+ ( a ~ Maybe Bool, b ~ Maybe Bool
543+ ) => LabelOptic "uniqueItems" A_Lens ParamOtherSchema ParamOtherSchema a b where
544+ labelOptic = #paramSchema % #uniqueItems
545+ {-# INLINE labelOptic #-}
546+
547+-- #enum
548+
549+instance
550+ ( a ~ Maybe [Value], b ~ Maybe [Value]
551+ ) => LabelOptic "enum" A_Lens Header Header a b where
552+ labelOptic = #paramSchema % #enum
553+ {-# INLINE labelOptic #-}
554+
555+instance
556+ ( a ~ Maybe [Value], b ~ Maybe [Value]
557+ ) => LabelOptic "enum" A_Lens Schema Schema a b where
558+ labelOptic = #paramSchema % #enum
559+ {-# INLINE labelOptic #-}
560+
561+instance
562+ ( a ~ Maybe [Value], b ~ Maybe [Value]
563+ ) => LabelOptic "enum" A_Lens NamedSchema NamedSchema a b where
564+ labelOptic = #paramSchema % #enum
565+ {-# INLINE labelOptic #-}
566+
567+instance
568+ ( a ~ Maybe [Value], b ~ Maybe [Value]
569+ ) => LabelOptic "enum" A_Lens ParamOtherSchema ParamOtherSchema a b where
570+ labelOptic = #paramSchema % #enum
571+ {-# INLINE labelOptic #-}
572+
573+-- #multipleOf
574+
575+instance
576+ ( a ~ Maybe Scientific, b ~ Maybe Scientific
577+ ) => LabelOptic "multipleOf" A_Lens Header Header a b where
578+ labelOptic = #paramSchema % #multipleOf
579+ {-# INLINE labelOptic #-}
580+
581+instance
582+ ( a ~ Maybe Scientific, b ~ Maybe Scientific
583+ ) => LabelOptic "multipleOf" A_Lens Schema Schema a b where
584+ labelOptic = #paramSchema % #multipleOf
585+ {-# INLINE labelOptic #-}
586+
587+instance
588+ ( a ~ Maybe Scientific, b ~ Maybe Scientific
589+ ) => LabelOptic "multipleOf" A_Lens NamedSchema NamedSchema a b where
590+ labelOptic = #paramSchema % #multipleOf
591+ {-# INLINE labelOptic #-}
592+
593+instance
594+ ( a ~ Maybe Scientific, b ~ Maybe Scientific
595+ ) => LabelOptic "multipleOf" A_Lens ParamOtherSchema ParamOtherSchema a b where
596+ labelOptic = #paramSchema % #multipleOf
597+ {-# INLINE labelOptic #-}
src/Data/Swagger/ParamSchema.hs+5−2
@@ -1,7 +1,5 @@
11-- |
22-- Module: Data.Swagger.ParamSchema
3−-- Copyright: (c) 2015 GetShopTV
4−-- License: BSD3
53-- Maintainer: Nickolay Kudasov <nickolay@getshoptv.com>
64-- Stability: experimental
75--
@@ -14,6 +12,11 @@ module Data.Swagger.ParamSchema (
1412 genericToParamSchema,
1513 toParamSchemaBoundedIntegral,
1614
15+ -- * Schema templates
16+ passwordParamSchema,
17+ binaryParamSchema,
18+ byteParamSchema,
19+
1720 -- * Generic encoding configuration
1821 SchemaOptions(..),
1922 defaultSchemaOptions,
src/Data/Swagger/Schema.hs+24−2
@@ -1,7 +1,5 @@
11-- |
22-- Module: Data.Swagger.Schema
3−-- Copyright: (c) 2015 GetShopTV
4−-- License: BSD3
53-- Maintainer: Nickolay Kudasov <nickolay@getshoptv.com>
64-- Stability: experimental
75--
@@ -19,11 +17,34 @@ module Data.Swagger.Schema (
1917 -- * Generic schema encoding
2018 genericDeclareNamedSchema,
2119 genericDeclareSchema,
20+ genericDeclareNamedSchemaNewtype,
21+ genericNameSchema,
22+
23+ -- ** 'Bounded' 'Integral'
2224 genericToNamedSchemaBoundedIntegral,
2325 toSchemaBoundedIntegral,
26+
27+ -- ** 'Bounded' 'Enum' key mappings
28+ declareSchemaBoundedEnumKeyMapping,
29+ toSchemaBoundedEnumKeyMapping,
30+
31+ -- ** Reusing 'ToParamSchema'
2432 paramSchemaToNamedSchema,
2533 paramSchemaToSchema,
2634
35+ -- ** Unrestricted versions
36+ genericDeclareNamedSchemaUnrestricted,
37+ genericDeclareSchemaUnrestricted,
38+
39+ -- * Schema templates
40+ passwordSchema,
41+ binarySchema,
42+ byteSchema,
43+
44+ -- * Sketching @'Schema'@s using @'ToJSON'@
45+ sketchSchema,
46+ sketchStrictSchema,
47+
2748 -- * Inlining @'Schema'@s
2849 inlineNonRecursiveSchemas,
2950 inlineAllSchemas,
@@ -33,6 +54,7 @@ module Data.Swagger.Schema (
3354 -- * Generic encoding configuration
3455 SchemaOptions(..),
3556 defaultSchemaOptions,
57+ fromAesonOptions,
3658) where
3759
3860import Data.Swagger.Internal.Schema
src/Data/Swagger/Schema/Generator.hsnew file+114
@@ -0,0 +1,114 @@
1+{-# LANGUAGE GADTs #-}
2+{-# LANGUAGE OverloadedLists #-}
3+{-# LANGUAGE ScopedTypeVariables #-}
4+
5+module Data.Swagger.Schema.Generator where
6+
7+import Prelude ()
8+import Prelude.Compat
9+
10+import Control.Lens.Operators
11+import Control.Monad (filterM)
12+import Data.Aeson
13+import Data.Aeson.Types
14+import qualified Data.HashMap.Strict.InsOrd as M
15+import Data.Maybe
16+import Data.Maybe
17+import Data.Proxy
18+import Data.Scientific
19+import qualified Data.Set as S
20+import Data.Swagger
21+import Data.Swagger.Declare
22+import Data.Swagger.Internal.Schema.Validation (inferSchemaTypes)
23+import qualified Data.Text as T
24+import qualified Data.Vector as V
25+import Test.QuickCheck (arbitrary)
26+import Test.QuickCheck.Gen
27+import Test.QuickCheck.Property
28+
29+-- | Note: 'schemaGen' may 'error', if schema type is not specified,
30+-- and cannot be inferred.
31+schemaGen :: Definitions Schema -> Schema -> Gen Value
32+schemaGen _ schema
33+ | Just cases <- schema ^. paramSchema . enum_ = elements cases
34+schemaGen defns schema =
35+ case schema ^. type_ of
36+ Nothing ->
37+ case inferSchemaTypes schema of
38+ [ inferredType ] -> schemaGen defns (schema & type_ ?~ inferredType)
39+ -- Gen is not MonadFail
40+ _ -> error "unable to infer schema type"
41+ Just SwaggerBoolean -> Bool <$> elements [True, False]
42+ Just SwaggerNull -> pure Null
43+ Just SwaggerNumber
44+ | Just min <- schema ^. minimum_
45+ , Just max <- schema ^. maximum_ ->
46+ Number . fromFloatDigits <$>
47+ choose (toRealFloat min, toRealFloat max :: Double)
48+ | otherwise -> Number .fromFloatDigits <$> (arbitrary :: Gen Double)
49+ Just SwaggerInteger
50+ | Just min <- schema ^. minimum_
51+ , Just max <- schema ^. maximum_ ->
52+ Number . fromInteger <$>
53+ choose (truncate min, truncate max)
54+ | otherwise -> Number . fromInteger <$> arbitrary
55+ Just SwaggerArray
56+ | Just 0 <- schema ^. maxLength -> pure $ Array V.empty
57+ | Just items <- schema ^. items ->
58+ case items of
59+ SwaggerItemsObject ref -> do
60+ size <- getSize
61+ let itemSchema = dereference defns ref
62+ minLength' = fromMaybe 0 $ fromInteger <$> schema ^. minItems
63+ maxLength' = fromMaybe size $ fromInteger <$> schema ^. maxItems
64+ arrayLength <- choose (minLength', max minLength' maxLength')
65+ generatedArray <- vectorOf arrayLength $ schemaGen defns itemSchema
66+ return . Array $ V.fromList generatedArray
67+ SwaggerItemsArray refs ->
68+ let itemGens = schemaGen defns . dereference defns <$> refs
69+ in fmap (Array . V.fromList) $ sequence itemGens
70+ Just SwaggerString -> do
71+ size <- getSize
72+ let minLength' = fromMaybe 0 $ fromInteger <$> schema ^. minLength
73+ let maxLength' = fromMaybe size $ fromInteger <$> schema ^. maxLength
74+ length <- choose (minLength', max minLength' maxLength')
75+ str <- vectorOf length arbitrary
76+ return . String $ T.pack str
77+ Just SwaggerObject -> do
78+ size <- getSize
79+ let props = dereference defns <$> schema ^. properties
80+ reqKeys = S.fromList $ schema ^. required
81+ allKeys = S.fromList . M.keys $ schema ^. properties
82+ optionalKeys = allKeys S.\\ reqKeys
83+ minProps' = fromMaybe (length reqKeys) $
84+ fromInteger <$> schema ^. minProperties
85+ maxProps' = fromMaybe size $ fromInteger <$> schema ^. maxProperties
86+ shuffledOptional <- shuffle $ S.toList optionalKeys
87+ numProps <- choose (minProps', max minProps' maxProps')
88+ let presentKeys = take numProps $ S.toList reqKeys ++ shuffledOptional
89+ let presentProps = M.filterWithKey (\k _ -> k `elem` presentKeys) props
90+ let gens = schemaGen defns <$> presentProps
91+ additionalGens <- case schema ^. additionalProperties of
92+ Just (AdditionalPropertiesSchema addlSchema) -> do
93+ additionalKeys <- sequence . take (numProps - length presentProps) . repeat $ T.pack <$> arbitrary
94+ return . M.fromList $ zip additionalKeys (repeat . schemaGen defns $ dereference defns addlSchema)
95+ _ -> return []
96+ x <- sequence $ gens <> additionalGens
97+ return . Object $ M.toHashMap x
98+ where
99+ dereference :: Definitions a -> Referenced a -> a
100+ dereference _ (Inline a) = a
101+ dereference defs (Ref (Reference ref)) = fromJust $ M.lookup ref defs
102+
103+genValue :: (ToSchema a) => Proxy a -> Gen Value
104+genValue p =
105+ let (defs, NamedSchema _ schema) = runDeclare (declareNamedSchema p) M.empty
106+ in schemaGen defs schema
107+
108+validateFromJSON :: forall a . (ToSchema a, FromJSON a) => Proxy a -> Property
109+validateFromJSON p = forAll (genValue p) $
110+ \val -> case parseEither parseJSON val of
111+ Right (_ :: a) -> succeeded
112+ Left err -> failed
113+ { reason = err
114+ }
src/Data/Swagger/Schema/Validate.hsdeleted−168
@@ -1,168 +0,0 @@
1−{-# LANGUAGE DeriveFunctor #-}
2−{-# LANGUAGE GADTs #-}
3−{-# LANGUAGE GeneralizedNewtypeDeriving #-}
4−{-# LANGUAGE PackageImports #-}
5−{-# LANGUAGE RankNTypes #-}
6−-- |
7−-- Module: Data.Swagger.Schema.Validate
8−-- Copyright: (c) 2015 GetShopTV
9−-- License: BSD3
10−-- Maintainer: Nickolay Kudasov <nickolay@getshoptv.com>
11−-- Stability: experimental
12−--
13−-- Validate JSON values with Swagger Schema.
14−module Data.Swagger.Schema.Validate where
15−
16−import Control.Applicative
17−import Control.Lens
18−import Control.Monad.Reader
19−
20−import Data.Aeson
21−import Data.Foldable (traverse_, for_)
22−import Data.HashMap.Strict (HashMap)
23−import qualified Data.HashMap.Strict as HashMap
24−import qualified "unordered-containers" Data.HashSet as HashSet
25−import Data.Scientific (isInteger)
26−import Data.Text (Text)
27−import qualified Data.Text as Text
28−import qualified Data.Vector as Vector
29−
30−import Data.Swagger.Internal
31−import Data.Swagger.Lens
32−
33−data ValidationResult a
34− = ValidationFailed [ValidationError]
35− | ValidationPassed a
36− deriving (Eq, Show, Functor)
37−
38−instance Applicative ValidationResult where
39− pure = ValidationPassed
40− ValidationPassed f <*> ValidationPassed x = ValidationPassed (f x)
41− ValidationFailed xs <*> ValidationFailed ys = ValidationFailed (xs ++ ys)
42− ValidationFailed xs <*> _ = ValidationFailed xs
43− _ <*> ValidationFailed ys = ValidationFailed ys
44−
45−instance Alternative ValidationResult where
46− empty = ValidationFailed []
47− ValidationPassed x <|> _ = ValidationPassed x
48− _ <|> y = y
49−
50−instance Monad ValidationResult where
51− return = pure
52− ValidationPassed x >>= f = f x
53− ValidationFailed msg >>= _ = ValidationFailed msg
54−
55−newtype Validation a = Validation { runValidation :: ReaderT (HashMap Text Schema) ValidationResult a }
56− deriving (Functor, Applicative, Alternative, Monad, MonadReader (HashMap Text Schema))
57−
58−invalid :: String -> Validation a
59−invalid msg = Validation (ReaderT (const (ValidationFailed [msg])))
60−
61−valid :: Validation ()
62−valid = pure ()
63−
64−unref :: Reference -> Validation Schema
65−unref (Reference ref) = do
66− ms <- asks (HashMap.lookup ref)
67− case ms of
68− Nothing -> invalid $ "unknown schema " ++ show ref
69− Just s -> pure s
70−
71−type ValidationError = String
72−
73−validateWithSchemaRef :: Referenced Schema -> Value -> Validation ()
74−validateWithSchemaRef (Ref ref) js = unref ref >>= flip validateWithSchema js
75−validateWithSchemaRef (Inline s) js = validateWithSchema s js
76−
77−validateWithSchema :: Schema -> Value -> Validation ()
78−validateWithSchema schema value
79− = validateType
80− *> validateEnum
81−
82− where
83− when' :: (a -> Bool) -> Lens' Schema (Maybe a) -> (a -> Validation ()) -> Validation ()
84− when' p l m = do
85− case schema ^. l of
86− Nothing -> valid
87− Just x -> when (p x) (m x)
88−
89− validateType =
90− case (schema ^. type_, value) of
91− (SwaggerNull, Null) -> valid
92− (SwaggerBoolean, Bool _) -> valid
93− (SwaggerInteger, Number n) -> validateInteger n
94− (SwaggerNumber, Number n) -> validateNumber n
95− (SwaggerString, String s) -> validateString s
96− (SwaggerArray, Array xs) -> validateArray xs
97− (SwaggerObject, Object o) -> validateObject o
98−
99− validateInteger n
100− = when (not (isInteger n)) (invalid $ "not an integer: " ++ show n)
101− *> validateNumber n
102−
103− exMax = Just True == schema ^. exclusiveMaximum
104− exMin = Just True == schema ^. exclusiveMinimum
105−
106− validateNumber n
107− = (if exMax
108− then when' (n >=) maximum_ $ \m ->
109− invalid $ "value " ++ show n ++ " exceeds maximum (should be <" ++ show m ++ ")"
110− else when' (n >) maximum_ $ \m ->
111− invalid $ "value " ++ show n ++ " exceeds maximum (should be <=" ++ show m ++ ")")
112− *> (if exMin
113− then when' (n <=) minimum_ $ \m ->
114− invalid $ "value " ++ show n ++ " is less than minimum (should be >" ++ show m ++ ")"
115− else when' (n <) minimum_ $ \m ->
116− invalid $ "value " ++ show n ++ " is less than minimum (should be >=" ++ show m ++ ")")
117− *> when' (not . isInteger . (n /)) multipleOf
118− (\k -> invalid $ "expected a multiple of " ++ show k ++ " but got " ++ show n)
119−
120− -- TODO: validate schemaPattern
121− validateString s
122− = when' (fromIntegral (Text.length s) >) maxLength
123− (\n -> invalid $ "string exceeds maximum length (should be <=" ++ show n ++ "): " ++ show s)
124− *> when' (fromIntegral (Text.length s) <) minLength
125− (\n -> invalid $ "string is too short (length should be >=" ++ show n ++ "): " ++ show s)
126−
127− validateArray xs
128− = when' (fromIntegral (Vector.length xs) >) maxItems
129− (\n -> invalid $ "array exceeds maximum size (should be <=" ++ show n ++ "): " ++ show (encode xs))
130− *> when' (fromIntegral (Vector.length xs) <) minItems
131− (\n -> invalid $ "array is too short (size should be >=" ++ show n ++ "): " ++ show (encode xs))
132− *> case schema ^. items of
133− Just (SwaggerItemsObject itemSchema) -> traverse_ (validateWithSchemaRef itemSchema) xs
134− Just (SwaggerItemsArray itemSchemas) ->
135− when (Vector.length xs /= length itemSchemas)
136− (invalid ("array size is invalid (should be exactly " ++ show (length itemSchemas) ++ "): " ++ show (encode xs)))
137− *> sequence_ (zipWith validateWithSchemaRef itemSchemas (Vector.toList xs))
138− Nothing -> invalid "invalid schema: array item schema expected"
139− *> when ((Just True == schema ^. uniqueItems) && not allUnique)
140− (invalid $ "array is expected to contain unique items, but it does not: " ++ show (encode xs))
141− where
142− allUnique = Vector.length xs == HashSet.size (HashSet.fromList (Vector.toList xs))
143−
144− validateObject o = case schema ^. schemaDiscriminator of
145− Just name -> validateWithSchemaRef (Ref (Reference name)) value
146− Nothing ->
147− when' (fromIntegral (HashMap.size o) >) schemaMaxProperties
148− (\n -> invalid $ "object size exceeds maximum (total number of properties should be <=" ++ show n ++ "): " ++ show (encode o))
149− *> when' (fromIntegral (HashMap.size o) <) schemaMaxProperties
150− (\n -> invalid $ "object size is too small (total number of properties should be >=" ++ show n ++ "): " ++ show (encode o))
151− *> validateRequired
152− *> validateProps
153− where
154− validateRequired = traverse_ validateReq (schema ^. schemaRequired)
155− validateReq name = when (not (HashMap.member name o))
156− (invalid $ "property " ++ show name ++ " is required, but not found in " ++ show (encode o))
157−
158− validateProps = for_ (HashMap.toList o) $ \(k, v) ->
159− case HashMap.lookup k (schema ^. schemaProperties) of
160− Nothing -> case schema ^. schemaAdditionalProperties of
161− Nothing -> valid -- TODO: issue a warning
162− Just s -> validateWithSchema s v
163− Just s -> validateWithSchemaRef s v
164−
165− validateEnum = case schema ^. enum_ of
166− Nothing -> valid
167− Just xs -> when (value `notElem` xs) $ invalid $ "expected one of " ++ show (encode xs) ++ " but got " ++ show value
168−
src/Data/Swagger/Schema/Validation.hsnew file+90
@@ -0,0 +1,90 @@
1+-- |
2+-- Module: Data.Swagger.Schema.Validation
3+-- Maintainer: Nickolay Kudasov <nickolay@getshoptv.com>
4+-- Stability: experimental
5+--
6+-- Validate JSON values with Swagger Schema.
7+module Data.Swagger.Schema.Validation (
8+ -- * How to use validation
9+ -- $howto
10+
11+ -- ** Examples
12+ -- $examples
13+
14+ -- ** Validating @'Maybe'@
15+ -- $maybe
16+
17+ -- * JSON validation
18+
19+ ValidationError,
20+
21+ -- ** Using 'ToJSON' and 'ToSchema'
22+ validatePrettyToJSON,
23+ validateToJSON,
24+ validateToJSONWithPatternChecker,
25+ renderValidationErrors,
26+
27+ -- ** Using 'Value' and 'Schema'
28+ validateJSON,
29+ validateJSONWithPatternChecker,
30+) where
31+
32+import Data.Swagger.Internal.Schema.Validation
33+
34+-- $setup
35+-- >>> import Control.Lens
36+-- >>> import Data.Aeson
37+-- >>> import Data.Proxy
38+-- >>> import Data.Swagger
39+-- >>> import GHC.Generics
40+-- >>> :set -XDeriveGeneric
41+
42+-- $howto
43+--
44+-- This module provides helpful functions for JSON validation.
45+-- These functions are meant to be used in test suites for your application
46+-- to ensure that JSON respresentation for your data corresponds to
47+-- schemas you're using for the Swagger specification.
48+--
49+-- It is recommended to use validation functions as QuickCheck properties
50+-- (see <http://hackage.haskell.org/package/QuickCheck>).
51+
52+-- $examples
53+--
54+-- >>> validateToJSON "hello"
55+-- []
56+--
57+-- >>> validateToJSON False
58+-- []
59+--
60+-- >>> newtype Nat = Nat Integer deriving Generic
61+-- >>> instance ToJSON Nat where toJSON (Nat n) = toJSON n
62+-- >>> instance ToSchema Nat where declareNamedSchema proxy = genericDeclareNamedSchema defaultSchemaOptions proxy & mapped.minimum_ ?~ 0
63+-- >>> validateToJSON (Nat 10)
64+-- []
65+-- >>> validateToJSON (Nat (-5))
66+-- ["value -5.0 falls below minimum (should be >=0.0)"]
67+
68+-- $maybe
69+--
70+-- Because @'Maybe' a@ has the same schema as @a@, validation
71+-- generally fails for @null@ JSON:
72+--
73+-- >>> validateToJSON (Nothing :: Maybe String)
74+-- ["expected JSON value of type SwaggerString"]
75+-- >>> validateToJSON ([Just "hello", Nothing] :: [Maybe String])
76+-- ["expected JSON value of type SwaggerString"]
77+-- >>> validateToJSON (123, Nothing :: Maybe String)
78+-- ["expected JSON value of type SwaggerString"]
79+--
80+-- However, when @'Maybe' a@ is a type of a record field,
81+-- validation takes @'required'@ property of the @'Schema'@
82+-- into account:
83+--
84+-- >>> data Person = Person { name :: String, age :: Maybe Int } deriving Generic
85+-- >>> instance ToJSON Person
86+-- >>> instance ToSchema Person
87+-- >>> validateToJSON (Person "Nick" (Just 24))
88+-- []
89+-- >>> validateToJSON (Person "Nick" Nothing)
90+-- []
src/Data/Swagger/SchemaOptions.hs+35
@@ -1,5 +1,14 @@
1+{-# LANGUAGE RecordWildCards #-}
2+-- |
3+-- Module: Data.Swagger.SchemaOptions
4+-- Maintainer: Nickolay Kudasov <nickolay@getshoptv.com>
5+-- Stability: experimental
6+--
7+-- Generic deriving options for @'ToParamSchema'@ and @'ToSchema'@.
18module Data.Swagger.SchemaOptions where
29
10+import qualified Data.Aeson.Types as Aeson
11+
312-- | Options that specify how to encode your type to Swagger schema.
413data SchemaOptions = SchemaOptions
514 { -- | Function applied to field labels. Handy for removing common record prefixes for example.
@@ -35,3 +44,29 @@ defaultSchemaOptions = SchemaOptions
3544 , unwrapUnaryRecords = False
3645 }
3746
47+-- | Convert 'Aeson.Options' to 'SchemaOptions'.
48+--
49+-- Specifically the following fields get copied:
50+--
51+-- * 'fieldLabelModifier'
52+-- * 'constructorTagModifier'
53+-- * 'allNullaryToStringTag'
54+-- * 'unwrapUnaryRecords'
55+--
56+-- Note that these fields have no effect on `SchemaOptions`:
57+--
58+-- * 'Aeson.omitNothingFields'
59+-- * 'Aeson.sumEncoding'
60+-- * 'Aeson.tagSingleConstructors'
61+--
62+-- The rest is defined as in 'defaultSchemaOptions'.
63+--
64+-- @since 2.2.1
65+--
66+fromAesonOptions :: Aeson.Options -> SchemaOptions
67+fromAesonOptions opts = defaultSchemaOptions
68+ { fieldLabelModifier = Aeson.fieldLabelModifier opts
69+ , constructorTagModifier = Aeson.constructorTagModifier opts
70+ , allNullaryToStringTag = Aeson.allNullaryToStringTag opts
71+ , unwrapUnaryRecords = Aeson.unwrapUnaryRecords opts
72+ }
stack-lts-2.yamldeleted−5
@@ -1,5 +0,0 @@
1−flags: {}
2−packages:
3−- '.'
4−extra-deps: []
5−resolver: lts-2.22
stack.yaml+7−3
@@ -1,5 +1,9 @@
1−flags: {}
1+resolver: lts-14.3
22packages:
33- '.'
4−extra-deps: []
5−resolver: lts-3.22
4+extra-deps:
5+- optics-core-0.2
6+- optics-th-0.2
7+- optics-extra-0.2
8+- indexed-profunctors-0.1
9+- insert-ordered-containers-0.2.3
swagger2.cabal+105−40
@@ -1,23 +1,38 @@
1+cabal-version: >=1.10
12name: swagger2
2−version: 1.2.1
3+version: 2.5
4+
35synopsis: Swagger 2.0 data model
4−description: Please see README.md
6+category: Web, Swagger
7+description:
8+ This library is intended to be used for decoding and encoding Swagger 2.0 API
9+ specifications as well as manipulating them.
10+ .
11+ The original Swagger 2.0 specification is available at http://swagger.io/specification/.
12+
513homepage: https://github.com/GetShopTV/swagger2
614bug-reports: https://github.com/GetShopTV/swagger2/issues
715license: BSD3
816license-file: LICENSE
917author: Nickolay Kudasov
1018maintainer: nickolay@getshoptv.com
11−copyright: (c) 2015, GetShopTV
12−category: Web
13−build-type: Simple
19+copyright: (c) 2015-2016, GetShopTV
20+build-type: Custom
1421extra-source-files:
1522 README.md
1623 , CHANGELOG.md
1724 , examples/*.hs
1825 , include/overlapping-compat.h
19−cabal-version: >=1.10
20−tested-with: GHC==7.8.4, GHC==7.10.3
26+tested-with:
27+ GHC ==8.0.2
28+ || ==8.2.2
29+ || ==8.4.4
30+ || ==8.6.5
31+ || ==8.8.1
32+
33+custom-setup
34+ setup-depends:
35+ base, Cabal, cabal-doctest >=1.0.6 && <1.1
2136
2237library
2338 hs-source-dirs: src
@@ -26,62 +41,112 @@ library
2641 Data.Swagger
2742 Data.Swagger.Declare
2843 Data.Swagger.Lens
44+ Data.Swagger.Operation
45+ Data.Swagger.Optics
2946 Data.Swagger.ParamSchema
3047 Data.Swagger.Schema
31− Data.Swagger.Schema.Validate
48+ Data.Swagger.Schema.Generator
49+ Data.Swagger.Schema.Validation
3250 Data.Swagger.SchemaOptions
3351
3452 -- internal modules
3553 Data.Swagger.Internal
3654 Data.Swagger.Internal.Schema
55+ Data.Swagger.Internal.Schema.Validation
3756 Data.Swagger.Internal.ParamSchema
3857 Data.Swagger.Internal.Utils
39− build-depends: base >=4.7 && <4.10
40− , base-compat >=0.6.0 && <0.10
41− , aeson
42− , containers
43− , hashable
44− , http-media
45− , lens
46− , mtl
47− , network
48− , scientific
49− , text
50− , template-haskell
51− , time
52− , transformers
53− , unordered-containers
54− , vector
58+ Data.Swagger.Internal.AesonUtils
59+ Data.Swagger.Internal.TypeShape
60+
61+ -- GHC boot libraries
62+ build-depends:
63+ base >=4.9 && <4.14
64+ , aeson-pretty >=0.8.7 && <0.9
65+ , bytestring >=0.10.4.0 && <0.11
66+ , containers >=0.5.5.1 && <0.7
67+ , template-haskell >=2.9.0.0 && <2.16
68+ , time >=1.4.2 && <1.10
69+ , transformers >=0.3.0.0 && <0.6
70+
71+ build-depends:
72+ mtl >=2.1 && <2.3
73+ , text >=1.2.3.0 && <1.3
74+
75+ -- other dependencies
76+ build-depends:
77+ base-compat-batteries >=0.10.4 && <0.12
78+ , aeson >=1.4.2.0 && <1.5
79+ -- cookie 0.4.3 is needed by GHC 7.8 due to time>=1.4 constraint
80+ , cookie >=0.4.3 && <0.5
81+ , generics-sop >=0.3.2.0 && <0.6
82+ , hashable >=1.2.7.0 && <1.4
83+ , http-media >=0.7.1.2 && <0.9
84+ , insert-ordered-containers >=0.2.3 && <0.3
85+ , lens >=4.16.1 && <4.19
86+ , network >=2.6.3.5 && <3.2
87+ , optics-core >=0.2 && <0.3
88+ , optics-th >=0.2 && <0.3
89+ , scientific >=0.3.6.2 && <0.4
90+ , transformers-compat >=0.3 && <0.7
91+ , unordered-containers >=0.2.9.0 && <0.3
92+ , uuid-types >=1.0.3 && <1.1
93+ , vector >=0.12.0.1 && <0.13
94+ , QuickCheck >=2.10.1 && <2.14
95+
5596 default-language: Haskell2010
5697
5798test-suite spec
5899 type: exitcode-stdio-1.0
59100 hs-source-dirs: test
60101 main-is: Spec.hs
61− build-depends: base
62− , base-compat
63− , swagger2
64− , hspec
65− , HUnit
66− , QuickCheck
67− , text
68− , aeson
69− , aeson-qq
70− , containers
71− , unordered-containers
72− , vector
73− , lens
102+
103+ -- From library parat
104+ -- We need aeson's toEncoding for doctests too
105+ build-depends:
106+ base
107+ , swagger2
108+ , aeson
109+ , base-compat-batteries
110+ , bytestring
111+ , containers
112+ , hashable
113+ , insert-ordered-containers
114+ , lens
115+ , mtl
116+ , template-haskell
117+ , text
118+ , time
119+ , unordered-containers
120+ , vector
121+ , QuickCheck
122+
123+ -- test-suite only dependencies
124+ build-depends:
125+ hspec >=2.5.5 && <2.8
126+ , HUnit >=1.6.0.0 && <1.7
127+ , quickcheck-instances >=0.3.19 && <0.14
128+ , utf8-string >=1.0.1.1 && <1.1
129+
130+ -- https://github.com/haskell/cabal/issues/3708
131+ build-tool-depends:
132+ hspec-discover:hspec-discover >=2.5.5 && <2.8
133+
74134 other-modules:
75135 SpecCommon
76136 Data.SwaggerSpec
137+ Data.Swagger.CommonTestTypes
138+ Data.Swagger.ParamSchemaSpec
77139 Data.Swagger.SchemaSpec
140+ Data.Swagger.Schema.ValidationSpec
141+ Data.Swagger.Schema.GeneratorSpec
78142 default-language: Haskell2010
79143
80−test-suite doctest
81− build-depends: base, doctest, Glob
144+test-suite doctests
145+ -- See QuickCheck note in https://github.com/phadej/cabal-doctest#notes
146+ build-depends: base, doctest, Glob, QuickCheck
82147 default-language: Haskell2010
83148 hs-source-dirs: test
84− main-is: DocTest.hs
149+ main-is: doctests.hs
85150 type: exitcode-stdio-1.0
86151
87152source-repository head
test/Data/Swagger/CommonTestTypes.hsnew file+679
@@ -0,0 +1,679 @@
1+{-# LANGUAGE DeriveGeneric #-}
2+{-# LANGUAGE QuasiQuotes #-}
3+{-# LANGUAGE ScopedTypeVariables #-}
4+
5+module Data.Swagger.CommonTestTypes where
6+
7+import Prelude ()
8+import Prelude.Compat
9+
10+import Data.Aeson (ToJSON (..), ToJSONKey (..), Value)
11+import Data.Aeson.QQ.Simple
12+import Data.Aeson.Types (toJSONKeyText)
13+import Data.Char
14+import Data.Map (Map)
15+import Data.Proxy
16+import Data.Set (Set)
17+import qualified Data.Text as Text
18+import GHC.Generics
19+
20+import Data.Swagger
21+
22+-- ========================================================================
23+-- Unit type
24+-- ========================================================================
25+
26+data Unit = Unit deriving (Generic)
27+instance ToParamSchema Unit
28+instance ToSchema Unit
29+
30+unitSchemaJSON :: Value
31+unitSchemaJSON = [aesonQQ|
32+{
33+ "type": "string",
34+ "enum": ["Unit"]
35+}
36+|]
37+
38+-- ========================================================================
39+-- Color (enum)
40+-- ========================================================================
41+data Color
42+ = Red
43+ | Green
44+ | Blue
45+ deriving (Generic)
46+instance ToParamSchema Color
47+instance ToSchema Color
48+
49+colorSchemaJSON :: Value
50+colorSchemaJSON = [aesonQQ|
51+{
52+ "type": "string",
53+ "enum": ["Red", "Green", "Blue"]
54+}
55+|]
56+
57+-- ========================================================================
58+-- Shade (paramSchemaToNamedSchema)
59+-- ========================================================================
60+
61+data Shade = Dim | Bright deriving (Generic)
62+instance ToParamSchema Shade
63+
64+instance ToSchema Shade where declareNamedSchema = pure . paramSchemaToNamedSchema defaultSchemaOptions
65+
66+shadeSchemaJSON :: Value
67+shadeSchemaJSON = [aesonQQ|
68+{
69+ "type": "string",
70+ "enum": ["Dim", "Bright"]
71+}
72+|]
73+
74+-- ========================================================================
75+-- Paint (record with bounded enum property)
76+-- ========================================================================
77+
78+newtype Paint = Paint { color :: Color }
79+ deriving (Generic)
80+instance ToSchema Paint
81+
82+paintSchemaJSON :: Value
83+paintSchemaJSON = [aesonQQ|
84+{
85+ "type": "object",
86+ "properties":
87+ {
88+ "color":
89+ {
90+ "$ref": "#/definitions/Color"
91+ }
92+ },
93+ "required": ["color"]
94+}
95+|]
96+
97+paintInlinedSchemaJSON :: Value
98+paintInlinedSchemaJSON = [aesonQQ|
99+{
100+ "type": "object",
101+ "properties":
102+ {
103+ "color":
104+ {
105+ "type": "string",
106+ "enum": ["Red", "Green", "Blue"]
107+ }
108+ },
109+ "required": ["color"]
110+}
111+|]
112+
113+-- ========================================================================
114+-- Status (constructorTagModifier)
115+-- ========================================================================
116+
117+data Status
118+ = StatusOk
119+ | StatusError
120+ deriving (Generic)
121+
122+instance ToParamSchema Status where
123+ toParamSchema = genericToParamSchema defaultSchemaOptions
124+ { constructorTagModifier = map toLower . drop (length "Status") }
125+instance ToSchema Status where
126+ declareNamedSchema = genericDeclareNamedSchema defaultSchemaOptions
127+ { constructorTagModifier = map toLower . drop (length "Status") }
128+
129+statusSchemaJSON :: Value
130+statusSchemaJSON = [aesonQQ|
131+{
132+ "type": "string",
133+ "enum": ["ok", "error"]
134+}
135+|]
136+
137+-- ========================================================================
138+-- Email (newtype with unwrapUnaryRecords set to True)
139+-- ========================================================================
140+
141+newtype Email = Email { getEmail :: String }
142+ deriving (Generic)
143+instance ToParamSchema Email
144+instance ToSchema Email where
145+ declareNamedSchema = genericDeclareNamedSchema defaultSchemaOptions
146+ { unwrapUnaryRecords = True }
147+
148+emailSchemaJSON :: Value
149+emailSchemaJSON = [aesonQQ|
150+{
151+ "type": "string"
152+}
153+|]
154+
155+-- ========================================================================
156+-- UserId (non-record newtype)
157+-- ========================================================================
158+
159+newtype UserId = UserId Integer
160+ deriving (Eq, Ord, Generic)
161+instance ToParamSchema UserId
162+instance ToSchema UserId
163+
164+userIdSchemaJSON :: Value
165+userIdSchemaJSON = [aesonQQ|
166+{
167+ "type": "integer"
168+}
169+|]
170+
171+-- ========================================================================
172+-- UserGroup (set newtype)
173+-- ========================================================================
174+
175+newtype UserGroup = UserGroup (Set UserId)
176+ deriving (Generic)
177+instance ToSchema UserGroup
178+
179+userGroupSchemaJSON :: Value
180+userGroupSchemaJSON = [aesonQQ|
181+{
182+ "type": "array",
183+ "items": { "$ref": "#/definitions/UserId" },
184+ "uniqueItems": true
185+}
186+|]
187+
188+-- ========================================================================
189+-- Person (simple record with optional fields)
190+-- ========================================================================
191+data Person = Person
192+ { name :: String
193+ , phone :: Integer
194+ , email :: Maybe String
195+ } deriving (Generic)
196+
197+instance ToSchema Person
198+
199+personSchemaJSON :: Value
200+personSchemaJSON = [aesonQQ|
201+{
202+ "type": "object",
203+ "properties":
204+ {
205+ "name": { "type": "string" },
206+ "phone": { "type": "integer" },
207+ "email": { "type": "string" }
208+ },
209+ "required": ["name", "phone"]
210+}
211+|]
212+
213+-- ========================================================================
214+-- Player (record newtype)
215+-- ========================================================================
216+
217+newtype Player = Player
218+ { position :: Point
219+ } deriving (Generic)
220+instance ToSchema Player
221+
222+playerSchemaJSON :: Value
223+playerSchemaJSON = [aesonQQ|
224+{
225+ "type": "object",
226+ "properties":
227+ {
228+ "position":
229+ {
230+ "$ref": "#/definitions/Point"
231+ }
232+ },
233+ "required": ["position"]
234+}
235+|]
236+
237+newtype Players = Players [Inlined Player]
238+ deriving (Generic)
239+instance ToSchema Players
240+
241+playersSchemaJSON :: Value
242+playersSchemaJSON = [aesonQQ|
243+{
244+ "type": "array",
245+ "items":
246+ {
247+ "type": "object",
248+ "properties":
249+ {
250+ "position":
251+ {
252+ "$ref": "#/definitions/Point"
253+ }
254+ },
255+ "required": ["position"]
256+ }
257+}
258+|]
259+
260+-- ========================================================================
261+-- Character (sum type with ref and record in alternative)
262+-- ========================================================================
263+
264+data Character
265+ = PC Player
266+ | NPC { npcName :: String, npcPosition :: Point }
267+ deriving (Generic)
268+instance ToSchema Character
269+
270+characterSchemaJSON :: Value
271+characterSchemaJSON = [aesonQQ|
272+{
273+ "type": "object",
274+ "properties":
275+ {
276+ "PC": { "$ref": "#/definitions/Player" },
277+ "NPC":
278+ {
279+ "type": "object",
280+ "properties":
281+ {
282+ "npcName": { "type": "string" },
283+ "npcPosition": { "$ref": "#/definitions/Point" }
284+ },
285+ "required": ["npcName", "npcPosition"]
286+ }
287+ },
288+ "maxProperties": 1,
289+ "minProperties": 1
290+}
291+|]
292+
293+characterInlinedSchemaJSON :: Value
294+characterInlinedSchemaJSON = [aesonQQ|
295+{
296+ "type": "object",
297+ "properties":
298+ {
299+ "PC":
300+ {
301+ "type": "object",
302+ "properties":
303+ {
304+ "position":
305+ {
306+ "type": "object",
307+ "properties":
308+ {
309+ "x": { "type": "number", "format": "double" },
310+ "y": { "type": "number", "format": "double" }
311+ },
312+ "required": ["x", "y"]
313+ }
314+ },
315+ "required": ["position"]
316+ },
317+ "NPC":
318+ {
319+ "type": "object",
320+ "properties":
321+ {
322+ "npcName": { "type": "string" },
323+ "npcPosition":
324+ {
325+ "type": "object",
326+ "properties":
327+ {
328+ "x": { "type": "number", "format": "double" },
329+ "y": { "type": "number", "format": "double" }
330+ },
331+ "required": ["x", "y"]
332+ }
333+ },
334+ "required": ["npcName", "npcPosition"]
335+ }
336+ },
337+ "maxProperties": 1,
338+ "minProperties": 1
339+}
340+|]
341+
342+characterInlinedPlayerSchemaJSON :: Value
343+characterInlinedPlayerSchemaJSON = [aesonQQ|
344+{
345+ "type": "object",
346+ "properties":
347+ {
348+ "PC":
349+ {
350+ "type": "object",
351+ "properties":
352+ {
353+ "position":
354+ {
355+ "$ref": "#/definitions/Point"
356+ }
357+ },
358+ "required": ["position"]
359+ },
360+ "NPC":
361+ {
362+ "type": "object",
363+ "properties":
364+ {
365+ "npcName": { "type": "string" },
366+ "npcPosition": { "$ref": "#/definitions/Point" }
367+ },
368+ "required": ["npcName", "npcPosition"]
369+ }
370+ },
371+ "maxProperties": 1,
372+ "minProperties": 1
373+}
374+|]
375+
376+-- ========================================================================
377+-- ISPair (non-record product data type)
378+-- ========================================================================
379+data ISPair = ISPair Integer String
380+ deriving (Generic)
381+
382+instance ToSchema ISPair
383+
384+ispairSchemaJSON :: Value
385+ispairSchemaJSON = [aesonQQ|
386+{
387+ "type": "array",
388+ "items":
389+ [
390+ { "type": "integer" },
391+ { "type": "string" }
392+ ],
393+ "minItems": 2,
394+ "maxItems": 2
395+}
396+|]
397+
398+-- ========================================================================
399+-- Point (record data type with custom fieldLabelModifier)
400+-- ========================================================================
401+
402+data Point = Point
403+ { pointX :: Double
404+ , pointY :: Double
405+ } deriving (Generic)
406+
407+instance ToSchema Point where
408+ declareNamedSchema = genericDeclareNamedSchema defaultSchemaOptions
409+ { fieldLabelModifier = map toLower . drop (length "point") }
410+
411+pointSchemaJSON :: Value
412+pointSchemaJSON = [aesonQQ|
413+{
414+ "type": "object",
415+ "properties":
416+ {
417+ "x": { "type": "number", "format": "double" },
418+ "y": { "type": "number", "format": "double" }
419+ },
420+ "required": ["x", "y"]
421+}
422+|]
423+
424+-- ========================================================================
425+-- Point (record data type with multiple fields)
426+-- ========================================================================
427+
428+data Point5 = Point5
429+ { point5X :: Double
430+ , point5Y :: Double
431+ , point5Z :: Double
432+ , point5U :: Double
433+ , point5V :: Double -- 5 dimensional!
434+ } deriving (Generic)
435+
436+instance ToSchema Point5 where
437+ declareNamedSchema = genericDeclareNamedSchema defaultSchemaOptions
438+ { fieldLabelModifier = map toLower . drop (length "point5") }
439+
440+point5SchemaJSON :: Value
441+point5SchemaJSON = [aesonQQ|
442+{
443+ "type": "object",
444+ "properties":
445+ {
446+ "x": { "type": "number", "format": "double" },
447+ "y": { "type": "number", "format": "double" },
448+ "z": { "type": "number", "format": "double" },
449+ "u": { "type": "number", "format": "double" },
450+ "v": { "type": "number", "format": "double" }
451+ },
452+ "required": ["x", "y", "z", "u", "v"]
453+}
454+|]
455+
456+point5Properties :: [String]
457+point5Properties = ["x", "y", "z", "u", "v"]
458+
459+-- ========================================================================
460+-- MyRoseTree (custom datatypeNameModifier)
461+-- ========================================================================
462+
463+data MyRoseTree = MyRoseTree
464+ { root :: String
465+ , trees :: [MyRoseTree]
466+ } deriving (Generic)
467+
468+instance ToSchema MyRoseTree where
469+ declareNamedSchema = genericDeclareNamedSchema defaultSchemaOptions
470+ { datatypeNameModifier = drop (length "My") }
471+
472+myRoseTreeSchemaJSON :: Value
473+myRoseTreeSchemaJSON = [aesonQQ|
474+{
475+ "type": "object",
476+ "properties":
477+ {
478+ "root": { "type": "string" },
479+ "trees":
480+ {
481+ "type": "array",
482+ "items":
483+ {
484+ "$ref": "#/definitions/RoseTree"
485+ }
486+ }
487+ },
488+ "required": ["root", "trees"]
489+}
490+|]
491+
492+data MyRoseTree' = MyRoseTree'
493+ { root' :: String
494+ , trees' :: [MyRoseTree']
495+ } deriving (Generic)
496+
497+instance ToSchema MyRoseTree' where
498+ declareNamedSchema = genericDeclareNamedSchema defaultSchemaOptions
499+ { datatypeNameModifier = map toLower }
500+
501+myRoseTreeSchemaJSON' :: Value
502+myRoseTreeSchemaJSON' = [aesonQQ|
503+{
504+ "type": "object",
505+ "properties":
506+ {
507+ "root'": { "type": "string" },
508+ "trees'":
509+ {
510+ "type": "array",
511+ "items":
512+ {
513+ "$ref": "#/definitions/myrosetree'"
514+ }
515+ }
516+ },
517+ "required": ["root'", "trees'"]
518+}
519+|]
520+
521+-- ========================================================================
522+-- Inlined (newtype for inlining schemas)
523+-- ========================================================================
524+
525+newtype Inlined a = Inlined { getInlined :: a }
526+
527+instance ToSchema a => ToSchema (Inlined a) where
528+ declareNamedSchema _ = unname <$> declareNamedSchema (Proxy :: Proxy a)
529+ where
530+ unname (NamedSchema _ s) = NamedSchema Nothing s
531+
532+-- ========================================================================
533+-- Light (sum type with unwrapUnaryRecords)
534+-- ========================================================================
535+
536+data Light
537+ = NoLight
538+ | LightFreq Double
539+ | LightColor Color
540+ | LightWaveLength { waveLength :: Double }
541+ deriving (Generic)
542+
543+instance ToSchema Light where
544+ declareNamedSchema = genericDeclareNamedSchemaUnrestricted defaultSchemaOptions
545+ { unwrapUnaryRecords = True }
546+
547+lightSchemaJSON :: Value
548+lightSchemaJSON = [aesonQQ|
549+{
550+ "type": "object",
551+ "properties":
552+ {
553+ "NoLight": { "type": "array", "items": {}, "maxItems": 0, "example": [] },
554+ "LightFreq": { "type": "number", "format": "double" },
555+ "LightColor": { "$ref": "#/definitions/Color" },
556+ "LightWaveLength": { "type": "number", "format": "double" }
557+ },
558+ "maxProperties": 1,
559+ "minProperties": 1
560+}
561+|]
562+
563+lightInlinedSchemaJSON :: Value
564+lightInlinedSchemaJSON = [aesonQQ|
565+{
566+ "type": "object",
567+ "properties":
568+ {
569+ "NoLight": { "type": "array", "items": {}, "maxItems": 0, "example": [] },
570+ "LightFreq": { "type": "number", "format": "double" },
571+ "LightColor":
572+ {
573+ "type": "string",
574+ "enum": ["Red", "Green", "Blue"]
575+ },
576+ "LightWaveLength": { "type": "number", "format": "double" }
577+ },
578+ "maxProperties": 1,
579+ "minProperties": 1
580+}
581+|]
582+
583+-- ========================================================================
584+-- ResourceId (series of newtypes)
585+-- ========================================================================
586+
587+newtype Id = Id String deriving (Generic)
588+instance ToSchema Id
589+
590+newtype ResourceId = ResourceId Id deriving (Generic)
591+instance ToSchema ResourceId
592+
593+-- ========================================================================
594+-- ButtonImages (bounded enum key mapping)
595+-- ========================================================================
596+
597+data ButtonState = Neutral | Focus | Active | Hover | Disabled
598+ deriving (Show, Bounded, Enum, Generic)
599+
600+instance ToJSON ButtonState
601+instance ToSchema ButtonState
602+instance ToJSONKey ButtonState where toJSONKey = toJSONKeyText (Text.pack . show)
603+
604+type ImageUrl = Text.Text
605+
606+newtype ButtonImages = ButtonImages { getButtonImages :: Map ButtonState ImageUrl }
607+ deriving (Generic)
608+
609+instance ToJSON ButtonImages where
610+ toJSON = toJSON . getButtonImages
611+
612+instance ToSchema ButtonImages where
613+ declareNamedSchema = genericDeclareNamedSchemaNewtype defaultSchemaOptions
614+ declareSchemaBoundedEnumKeyMapping
615+
616+buttonImagesSchemaJSON :: Value
617+buttonImagesSchemaJSON = [aesonQQ|
618+{
619+ "type": "object",
620+ "properties":
621+ {
622+ "Neutral": { "type": "string" },
623+ "Focus": { "type": "string" },
624+ "Active": { "type": "string" },
625+ "Hover": { "type": "string" },
626+ "Disabled": { "type": "string" }
627+ }
628+}
629+|]
630+
631+-- ========================================================================
632+-- SingleMaybeField (single field data with optional field)
633+-- ========================================================================
634+
635+data SingleMaybeField = SingleMaybeField { singleMaybeField :: Maybe String }
636+ deriving (Show, Generic)
637+
638+instance ToJSON SingleMaybeField
639+instance ToSchema SingleMaybeField
640+
641+singleMaybeFieldSchemaJSON :: Value
642+singleMaybeFieldSchemaJSON = [aesonQQ|
643+{
644+ "type": "object",
645+ "properties":
646+ {
647+ "singleMaybeField": { "type": "string" }
648+ }
649+}
650+|]
651+
652+
653+-- ========================================================================
654+-- TimeOfDay
655+-- ========================================================================
656+data TimeOfDay
657+ = Int
658+ | Pico
659+ deriving (Generic)
660+instance ToSchema TimeOfDay
661+instance ToParamSchema TimeOfDay
662+
663+
664+timeOfDaySchemaJSON :: Value
665+timeOfDaySchemaJSON = [aesonQQ|
666+{
667+ "example": "12:33:15",
668+ "type": "string",
669+ "format": "hh:MM:ss"
670+}
671+|]
672+
673+timeOfDayParamSchemaJSON :: Value
674+timeOfDayParamSchemaJSON = [aesonQQ|
675+{
676+ "type": "string",
677+ "format": "hh:MM:ss"
678+}
679+|]
test/Data/Swagger/ParamSchemaSpec.hs+10−84
@@ -1,22 +1,29 @@
11{-# LANGUAGE DeriveGeneric #-}
2+{-# LANGUAGE DataKinds #-}
23{-# LANGUAGE ScopedTypeVariables #-}
34{-# LANGUAGE TemplateHaskell #-}
45{-# LANGUAGE QuasiQuotes #-}
6+{-# LANGUAGE OverloadedStrings #-}
57module Data.Swagger.ParamSchemaSpec where
68
79import Data.Aeson
8−import Data.Aeson.QQ
10+import Data.Aeson.QQ.Simple
911import Data.Char
1012import Data.Proxy
1113import GHC.Generics
1214
1315import Data.Swagger
16+import Data.Swagger.Internal (SwaggerKind(..))
1417
18+import Data.Swagger.CommonTestTypes
1519import SpecCommon
1620import Test.Hspec
21+import Data.Time.LocalTime
22+
23+import qualified Data.HashMap.Strict as HM
1724
1825checkToParamSchema :: ToParamSchema a => Proxy a -> Value -> Spec
19−checkToParamSchema proxy js = (toParamSchema proxy :: ParamSchema Param) <=> js
26+checkToParamSchema proxy js = (toParamSchema proxy :: ParamSchema ('SwaggerKindNormal Param)) <=> js
2027
2128spec :: Spec
2229spec = do
@@ -27,88 +34,7 @@ spec = do
2734 context "Unary records" $ do
2835 context "Email (unary record)" $ checkToParamSchema (Proxy :: Proxy Email) emailSchemaJSON
2936 context "UserId (non-record newtype)" $ checkToParamSchema (Proxy :: Proxy UserId) userIdSchemaJSON
37+ context "TimeOfDay" $ checkToParamSchema (Proxy :: Proxy Data.Time.LocalTime.TimeOfDay) timeOfDayParamSchemaJSON
3038
3139main :: IO ()
3240main = hspec spec
33−
34−-- ========================================================================
35−-- Unit type
36−-- ========================================================================
37−
38−data Unit = Unit deriving (Generic)
39−instance ToParamSchema Unit
40−
41−unitSchemaJSON :: Value
42−unitSchemaJSON = [aesonQQ|
43−{
44− "type": "string",
45− "enum": ["Unit"]
46−}
47−|]
48−
49−-- ========================================================================
50−-- Color (enum)
51−-- ========================================================================
52−data Color
53− = Red
54− | Green
55− | Blue
56− deriving (Generic)
57−instance ToParamSchema Color
58−
59−colorSchemaJSON :: Value
60−colorSchemaJSON = [aesonQQ|
61−{
62− "type": "string",
63− "enum": ["Red", "Green", "Blue"]
64−}
65−|]
66−
67−-- ========================================================================
68−-- Status (constructorTagModifier)
69−-- ========================================================================
70−
71−data Status = StatusOk | StatusError deriving (Generic)
72−
73−instance ToParamSchema Status where
74− toParamSchema = genericToParamSchema defaultSchemaOptions
75− { constructorTagModifier = map toLower . drop (length "Status") }
76−
77−statusSchemaJSON :: Value
78−statusSchemaJSON = [aesonQQ|
79−{
80− "type": "string",
81− "enum": ["ok", "error"]
82−}
83−|]
84−
85−-- ========================================================================
86−-- Email (newtype with unwrapUnaryRecords set to True)
87−-- ========================================================================
88−
89−newtype Email = Email { getEmail :: String }
90− deriving (Generic)
91−instance ToParamSchema Email
92−
93−emailSchemaJSON :: Value
94−emailSchemaJSON = [aesonQQ|
95−{
96− "type": "string"
97−}
98−|]
99−
100−-- ========================================================================
101−-- UserId (non-record newtype)
102−-- ========================================================================
103−
104−newtype UserId = UserId Integer
105− deriving (Generic)
106−instance ToParamSchema UserId
107−
108−userIdSchemaJSON :: Value
109−userIdSchemaJSON = [aesonQQ|
110−{
111− "type": "integer"
112−}
113−|]
114−
test/Data/Swagger/Schema/GeneratorSpec.hsnew file+168
@@ -0,0 +1,168 @@
1+{-# LANGUAGE OverloadedLists #-}
2+{-# LANGUAGE OverloadedStrings #-}
3+{-# LANGUAGE PackageImports #-}
4+module Data.Swagger.Schema.GeneratorSpec where
5+
6+import Prelude ()
7+import Prelude.Compat
8+
9+import Data.Swagger
10+import Data.Swagger.Schema.Generator
11+
12+import Control.Lens.Operators
13+import Data.Aeson
14+import Data.Hashable (Hashable)
15+import Data.HashMap.Strict (HashMap)
16+import qualified Data.HashMap.Strict as HashMap
17+import "unordered-containers" Data.HashSet (HashSet)
18+import qualified "unordered-containers" Data.HashSet as HashSet
19+import Data.Int
20+import Data.IntMap (IntMap)
21+import Data.List.NonEmpty.Compat (NonEmpty (..), nonEmpty)
22+import Data.Map (Map, fromList)
23+import Data.Monoid (mempty)
24+import Data.Proxy
25+import Data.Proxy
26+import Data.Set (Set)
27+import qualified Data.Text as T
28+import qualified Data.Text.Lazy as TL
29+import Data.Time
30+import Data.Version (Version)
31+import Data.Word
32+import GHC.Generics
33+
34+import Test.Hspec
35+import Test.Hspec.QuickCheck
36+import Test.QuickCheck
37+
38+shouldValidate :: (FromJSON a, ToSchema a) => Proxy a -> Property
39+shouldValidate = validateFromJSON
40+
41+
42+shouldNotValidate :: (FromJSON a, ToSchema a) => Proxy a -> Property
43+shouldNotValidate = expectFailure . shouldValidate
44+
45+
46+spec :: Spec
47+spec = do
48+ describe "FromJSON validation" $ do
49+ prop "Bool" $ shouldValidate (Proxy :: Proxy Bool)
50+ prop "Char" $ shouldValidate (Proxy :: Proxy Char)
51+ prop "Double" $ shouldValidate (Proxy :: Proxy Double)
52+ prop "Float" $ shouldValidate (Proxy :: Proxy Float)
53+ prop "Int" $ shouldValidate (Proxy :: Proxy Int)
54+ prop "Int8" $ shouldValidate (Proxy :: Proxy Int8)
55+ prop "Int16" $ shouldValidate (Proxy :: Proxy Int16)
56+ prop "Int32" $ shouldValidate (Proxy :: Proxy Int32)
57+ prop "Int64" $ shouldValidate (Proxy :: Proxy Int64)
58+ prop "Integer" $ shouldValidate (Proxy :: Proxy Integer)
59+ prop "Word" $ shouldValidate (Proxy :: Proxy Word)
60+ prop "Word8" $ shouldValidate (Proxy :: Proxy Word8)
61+ prop "Word16" $ shouldValidate (Proxy :: Proxy Word16)
62+ prop "Word32" $ shouldValidate (Proxy :: Proxy Word32)
63+ prop "Word64" $ shouldValidate (Proxy :: Proxy Word64)
64+ prop "String" $ shouldValidate (Proxy :: Proxy String)
65+ prop "()" $ shouldValidate (Proxy :: Proxy ())
66+-- prop "ZonedTime" $ shouldValidate (Proxy :: Proxy ZonedTime)
67+-- prop "UTCTime" $ shouldValidate (Proxy :: Proxy UTCTime)
68+ prop "T.Text" $ shouldValidate (Proxy :: Proxy T.Text)
69+ prop "TL.Text" $ shouldValidate (Proxy :: Proxy TL.Text)
70+ prop "[String]" $ shouldValidate (Proxy :: Proxy [String])
71+ -- prop "(Maybe [Int])" $ shouldValidate (Proxy :: Proxy (Maybe [Int]))
72+ prop "(IntMap String)" $ shouldValidate (Proxy :: Proxy (IntMap String))
73+ prop "(Set Bool)" $ shouldValidate (Proxy :: Proxy (Set Bool))
74+ prop "(NonEmpty Bool)" $ shouldValidate (Proxy :: Proxy (NonEmpty Bool))
75+ prop "(HashSet Bool)" $ shouldValidate (Proxy :: Proxy (HashSet Bool))
76+ prop "(Either Int String)" $ shouldValidate (Proxy :: Proxy (Either Int String))
77+ prop "(Int, String)" $ shouldValidate (Proxy :: Proxy (Int, String))
78+ prop "(Map String Int)" $ shouldValidate (Proxy :: Proxy (Map String Int))
79+ prop "(Map T.Text Int)" $ shouldValidate (Proxy :: Proxy (Map T.Text Int))
80+ prop "(Map TL.Text Bool)" $ shouldValidate (Proxy :: Proxy (Map TL.Text Bool))
81+ prop "(HashMap String Int)" $ shouldValidate (Proxy :: Proxy (HashMap String Int))
82+ prop "(HashMap T.Text Int)" $ shouldValidate (Proxy :: Proxy (HashMap T.Text Int))
83+ prop "(HashMap TL.Text Bool)" $ shouldValidate (Proxy :: Proxy (HashMap TL.Text Bool))
84+ prop "Object" $ shouldValidate (Proxy :: Proxy Object)
85+ prop "(Int, String, Double)" $ shouldValidate (Proxy :: Proxy (Int, String, Double))
86+ prop "(Int, String, Double, [Int])" $ shouldValidate (Proxy :: Proxy (Int, String, Double, [Int]))
87+ prop "(Int, String, Double, [Int], Int)" $ shouldValidate (Proxy :: Proxy (Int, String, Double, [Int], Int))
88+ describe "Invalid FromJSON validation" $ do
89+ prop "WrongType" $ shouldNotValidate (Proxy :: Proxy WrongType)
90+ prop "MissingRequired" $ shouldNotValidate (Proxy :: Proxy MissingRequired)
91+ prop "MissingProperty" $ shouldNotValidate (Proxy :: Proxy MissingProperty)
92+ prop "WrongPropType" $ shouldNotValidate (Proxy :: Proxy WrongPropType)
93+
94+-- =============================
95+-- Data types and bunk instances
96+-- =============================
97+
98+data WrongType = WrongType Bool
99+
100+instance FromJSON WrongType where
101+ parseJSON = withBool "WrongType" $ return . WrongType
102+
103+instance ToSchema WrongType where
104+ declareNamedSchema _ = return . NamedSchema (Just "WrongType") $
105+ mempty
106+ & type_ ?~ SwaggerObject
107+
108+
109+data MissingRequired = MissingRequired
110+ { propA :: String
111+ , propB :: Bool
112+ }
113+
114+instance FromJSON MissingRequired where
115+ parseJSON = withObject "MissingRequired" $ \o ->
116+ MissingRequired
117+ <$> o .: "propA"
118+ <*> o .: "propB"
119+
120+instance ToSchema MissingRequired where
121+ declareNamedSchema _ = do
122+ stringSchema <- declareSchemaRef (Proxy :: Proxy String)
123+ boolSchema <- declareSchemaRef (Proxy :: Proxy Bool)
124+ return . NamedSchema (Just "MissingRequired") $
125+ mempty
126+ & type_ ?~ SwaggerObject
127+ & properties .~ [("propA", stringSchema)
128+ ,("propB", boolSchema)
129+ ]
130+ & required .~ ["propA"]
131+
132+data MissingProperty = MissingProperty
133+ { propC :: String
134+ , propD :: Bool
135+ }
136+
137+instance FromJSON MissingProperty where
138+ parseJSON = withObject "MissingProperty" $ \o ->
139+ MissingProperty
140+ <$> o .: "propC"
141+ <*> o .: "propD"
142+
143+instance ToSchema MissingProperty where
144+ declareNamedSchema _ = do
145+ stringSchema <- declareSchemaRef (Proxy :: Proxy String)
146+ return . NamedSchema (Just "MissingProperty") $
147+ mempty
148+ & type_ ?~ SwaggerObject
149+ & properties .~ [("propC", stringSchema)]
150+ & required .~ ["propC"]
151+
152+data WrongPropType = WrongPropType
153+ { propE :: String
154+ }
155+
156+instance FromJSON WrongPropType where
157+ parseJSON = withObject "WrongPropType" $ \o ->
158+ WrongPropType
159+ <$> o .: "propE"
160+
161+instance ToSchema WrongPropType where
162+ declareNamedSchema _ = do
163+ boolSchema <- declareSchemaRef (Proxy :: Proxy Bool)
164+ return . NamedSchema (Just "WrongPropType") $
165+ mempty
166+ & type_ ?~ SwaggerObject
167+ & properties .~ [("propE", boolSchema)]
168+ & required .~ ["propE"]
test/Data/Swagger/Schema/ValidationSpec.hsnew file+278
@@ -0,0 +1,278 @@
1+{-# LANGUAGE CPP #-}
2+{-# LANGUAGE DeriveGeneric #-}
3+{-# LANGUAGE PackageImports #-}
4+{-# LANGUAGE RecordWildCards #-}
5+{-# LANGUAGE ScopedTypeVariables #-}
6+{-# OPTIONS_GHC -fno-warn-orphans #-}
7+module Data.Swagger.Schema.ValidationSpec where
8+
9+import Control.Applicative
10+import Control.Lens ((&), (.~), (?~))
11+import Data.Aeson
12+import Data.Aeson.Types
13+import Data.Hashable (Hashable)
14+import Data.HashMap.Strict (HashMap)
15+import qualified Data.HashMap.Strict as HashMap
16+import "unordered-containers" Data.HashSet (HashSet)
17+import qualified "unordered-containers" Data.HashSet as HashSet
18+import Data.Int
19+import Data.IntMap (IntMap)
20+import Data.List.NonEmpty.Compat (NonEmpty (..), nonEmpty)
21+import Data.Map (Map, fromList)
22+import Data.Monoid (mempty)
23+import Data.Proxy
24+import Data.Set (Set)
25+import qualified Data.Text as T
26+import qualified Data.Text.Lazy as TL
27+import Data.Time
28+import Data.Version (Version)
29+import Data.Word
30+import GHC.Generics
31+
32+import Data.Swagger
33+import Data.Swagger.Declare
34+
35+import Test.Hspec
36+import Test.Hspec.QuickCheck
37+import Test.QuickCheck
38+import Test.QuickCheck.Instances ()
39+
40+shouldValidate :: (ToJSON a, ToSchema a) => Proxy a -> a -> Bool
41+shouldValidate _ x = validateToJSON x == []
42+
43+shouldNotValidate :: forall a. ToSchema a => (a -> Value) -> a -> Bool
44+shouldNotValidate f = not . null . validateJSON defs sch . f
45+ where
46+ (defs, sch) = runDeclare (declareSchema (Proxy :: Proxy a)) mempty
47+
48+spec :: Spec
49+spec = do
50+ describe "Validation" $ do
51+ prop "Bool" $ shouldValidate (Proxy :: Proxy Bool)
52+ prop "Char" $ shouldValidate (Proxy :: Proxy Char)
53+ prop "Double" $ shouldValidate (Proxy :: Proxy Double)
54+ prop "Float" $ shouldValidate (Proxy :: Proxy Float)
55+ prop "Int" $ shouldValidate (Proxy :: Proxy Int)
56+ prop "Int8" $ shouldValidate (Proxy :: Proxy Int8)
57+ prop "Int16" $ shouldValidate (Proxy :: Proxy Int16)
58+ prop "Int32" $ shouldValidate (Proxy :: Proxy Int32)
59+ prop "Int64" $ shouldValidate (Proxy :: Proxy Int64)
60+ prop "Integer" $ shouldValidate (Proxy :: Proxy Integer)
61+ prop "Word" $ shouldValidate (Proxy :: Proxy Word)
62+ prop "Word8" $ shouldValidate (Proxy :: Proxy Word8)
63+ prop "Word16" $ shouldValidate (Proxy :: Proxy Word16)
64+ prop "Word32" $ shouldValidate (Proxy :: Proxy Word32)
65+ prop "Word64" $ shouldValidate (Proxy :: Proxy Word64)
66+ prop "String" $ shouldValidate (Proxy :: Proxy String)
67+ prop "()" $ shouldValidate (Proxy :: Proxy ())
68+ prop "ZonedTime" $ shouldValidate (Proxy :: Proxy ZonedTime)
69+ prop "UTCTime" $ shouldValidate (Proxy :: Proxy UTCTime)
70+ prop "T.Text" $ shouldValidate (Proxy :: Proxy T.Text)
71+ prop "TL.Text" $ shouldValidate (Proxy :: Proxy TL.Text)
72+ prop "[String]" $ shouldValidate (Proxy :: Proxy [String])
73+ -- prop "(Maybe [Int])" $ shouldValidate (Proxy :: Proxy (Maybe [Int]))
74+ prop "(IntMap String)" $ shouldValidate (Proxy :: Proxy (IntMap String))
75+ prop "(Set Bool)" $ shouldValidate (Proxy :: Proxy (Set Bool))
76+ prop "(NonEmpty Bool)" $ shouldValidate (Proxy :: Proxy (NonEmpty Bool))
77+ prop "(HashSet Bool)" $ shouldValidate (Proxy :: Proxy (HashSet Bool))
78+ prop "(Either Int String)" $ shouldValidate (Proxy :: Proxy (Either Int String))
79+ prop "(Int, String)" $ shouldValidate (Proxy :: Proxy (Int, String))
80+ prop "(Map String Int)" $ shouldValidate (Proxy :: Proxy (Map String Int))
81+ prop "(Map T.Text Int)" $ shouldValidate (Proxy :: Proxy (Map T.Text Int))
82+ prop "(Map TL.Text Bool)" $ shouldValidate (Proxy :: Proxy (Map TL.Text Bool))
83+ prop "(HashMap String Int)" $ shouldValidate (Proxy :: Proxy (HashMap String Int))
84+ prop "(HashMap T.Text Int)" $ shouldValidate (Proxy :: Proxy (HashMap T.Text Int))
85+ prop "(HashMap TL.Text Bool)" $ shouldValidate (Proxy :: Proxy (HashMap TL.Text Bool))
86+ prop "Object" $ shouldValidate (Proxy :: Proxy Object)
87+ prop "(Int, String, Double)" $ shouldValidate (Proxy :: Proxy (Int, String, Double))
88+ prop "(Int, String, Double, [Int])" $ shouldValidate (Proxy :: Proxy (Int, String, Double, [Int]))
89+ prop "(Int, String, Double, [Int], Int)" $ shouldValidate (Proxy :: Proxy (Int, String, Double, [Int], Int))
90+ prop "Person" $ shouldValidate (Proxy :: Proxy Person)
91+ prop "Color" $ shouldValidate (Proxy :: Proxy Color)
92+ prop "Paint" $ shouldValidate (Proxy :: Proxy Paint)
93+ prop "MyRoseTree" $ shouldValidate (Proxy :: Proxy MyRoseTree)
94+ prop "Light" $ shouldValidate (Proxy :: Proxy Light)
95+ prop "ButtonImages" $ shouldValidate (Proxy :: Proxy ButtonImages)
96+ prop "Version" $ shouldValidate (Proxy :: Proxy Version)
97+ prop "FreeForm" $ shouldValidate (Proxy :: Proxy FreeForm)
98+
99+ describe "invalid cases" $ do
100+ prop "invalidPersonToJSON" $ shouldNotValidate invalidPersonToJSON
101+ prop "invalidColorToJSON" $ shouldNotValidate invalidColorToJSON
102+ prop "invalidPaintToJSON" $ shouldNotValidate invalidPaintToJSON
103+ prop "invalidLightToJSON" $ shouldNotValidate invalidLightToJSON
104+ prop "invalidButtonImagesToJSON" $ shouldNotValidate invalidButtonImagesToJSON
105+
106+main :: IO ()
107+main = hspec spec
108+
109+-- ========================================================================
110+-- Person (simple record with optional fields)
111+-- ========================================================================
112+data Person = Person
113+ { name :: String
114+ , phone :: Integer
115+ , email :: Maybe String
116+ } deriving (Show, Generic)
117+
118+instance ToJSON Person
119+instance ToSchema Person
120+
121+instance Arbitrary Person where
122+ arbitrary = Person <$> arbitrary <*> arbitrary <*> arbitrary
123+
124+invalidPersonToJSON :: Person -> Value
125+invalidPersonToJSON Person{..} = object
126+ [ T.pack "personName" .= toJSON name
127+ , T.pack "personPhone" .= toJSON phone
128+ , T.pack "personEmail" .= toJSON email
129+ ]
130+
131+-- ========================================================================
132+-- Color (enum)
133+-- ========================================================================
134+data Color = Red | Green | Blue deriving (Show, Generic, Bounded, Enum)
135+
136+instance ToJSON Color
137+instance ToSchema Color
138+
139+instance Arbitrary Color where
140+ arbitrary = arbitraryBoundedEnum
141+
142+invalidColorToJSON :: Color -> Value
143+invalidColorToJSON Red = toJSON "red"
144+invalidColorToJSON Green = toJSON "green"
145+invalidColorToJSON Blue = toJSON "blue"
146+
147+-- ========================================================================
148+-- Paint (record with bounded enum property)
149+-- ========================================================================
150+
151+newtype Paint = Paint { color :: Color }
152+ deriving (Show, Generic)
153+
154+instance ToJSON Paint
155+instance ToSchema Paint
156+
157+instance Arbitrary Paint where
158+ arbitrary = Paint <$> arbitrary
159+
160+invalidPaintToJSON :: Paint -> Value
161+invalidPaintToJSON = toJSON . color
162+
163+-- ========================================================================
164+-- MyRoseTree (custom datatypeNameModifier)
165+-- ========================================================================
166+
167+data MyRoseTree = MyRoseTree
168+ { root :: String
169+ , trees :: [MyRoseTree]
170+ } deriving (Show, Generic)
171+
172+instance ToJSON MyRoseTree
173+
174+instance ToSchema MyRoseTree where
175+ declareNamedSchema = genericDeclareNamedSchema defaultSchemaOptions
176+ { datatypeNameModifier = drop (length "My") }
177+
178+instance Arbitrary MyRoseTree where
179+ arbitrary = fmap (cut limit) $ MyRoseTree <$> arbitrary <*> (take limit <$> arbitrary)
180+ where
181+ limit = 4
182+ cut 0 (MyRoseTree x _ ) = MyRoseTree x []
183+ cut n (MyRoseTree x xs) = MyRoseTree x (map (cut (n - 1)) xs)
184+
185+-- ========================================================================
186+-- Light (sum type)
187+-- ========================================================================
188+
189+data Light = NoLight | LightFreq Double | LightColor Color deriving (Show, Generic)
190+
191+instance ToSchema Light where
192+ declareNamedSchema = genericDeclareNamedSchemaUnrestricted defaultSchemaOptions
193+
194+instance ToJSON Light where
195+ toJSON = genericToJSON defaultOptions { sumEncoding = ObjectWithSingleField }
196+
197+instance Arbitrary Light where
198+ arbitrary = oneof
199+ [ return NoLight
200+ , LightFreq <$> arbitrary
201+ , LightColor <$> arbitrary
202+ ]
203+
204+invalidLightToJSON :: Light -> Value
205+invalidLightToJSON = genericToJSON defaultOptions
206+
207+-- ========================================================================
208+-- ButtonImages (bounded enum key mapping)
209+-- ========================================================================
210+
211+data ButtonState = Neutral | Focus | Active | Hover | Disabled
212+ deriving (Show, Eq, Ord, Bounded, Enum, Generic)
213+
214+instance ToJSON ButtonState
215+instance ToSchema ButtonState
216+instance ToJSONKey ButtonState where toJSONKey = toJSONKeyText (T.pack . show)
217+
218+instance Arbitrary ButtonState where
219+ arbitrary = arbitraryBoundedEnum
220+
221+type ImageUrl = T.Text
222+
223+newtype ButtonImages = ButtonImages { getButtonImages :: Map ButtonState ImageUrl }
224+ deriving (Show, Generic)
225+
226+instance ToJSON ButtonImages where
227+ toJSON = toJSON . getButtonImages
228+
229+instance ToSchema ButtonImages where
230+ declareNamedSchema = genericDeclareNamedSchemaNewtype defaultSchemaOptions
231+ declareSchemaBoundedEnumKeyMapping
232+
233+invalidButtonImagesToJSON :: ButtonImages -> Value
234+invalidButtonImagesToJSON = genericToJSON defaultOptions
235+
236+instance Arbitrary ButtonImages where
237+ arbitrary = ButtonImages <$> arbitrary
238+
239+-- ========================================================================
240+-- FreeForm (wraps a raw JSON Value)
241+-- ========================================================================
242+
243+data FreeForm = FreeForm { jsonContent :: Map T.Text Value }
244+ deriving (Show, Generic)
245+
246+instance ToJSON FreeForm where
247+ toJSON = toJSON . jsonContent
248+
249+instance ToSchema FreeForm where
250+ declareNamedSchema _ = pure $ NamedSchema (Just $ T.pack "FreeForm") $ mempty
251+ & type_ ?~ SwaggerObject
252+ & additionalProperties ?~ AdditionalPropertiesAllowed True
253+
254+instance Arbitrary FreeForm where
255+ arbitrary = (FreeForm . fromList) <$> genObj
256+ where
257+ genObj = listOf $ do
258+ k <- arbitrary
259+ v <- oneof [ String <$> arbitrary, Number <$> arbitrary, Bool <$> arbitrary, pure Null ]
260+ pure (k, v)
261+
262+instance Eq ZonedTime where
263+ ZonedTime t (TimeZone x _ _) == ZonedTime t' (TimeZone y _ _) = t == t' && x == y
264+
265+-- ========================================================================
266+-- Arbitrary instance for Data.Aeson.Value
267+-- ========================================================================
268+
269+instance Arbitrary Value where
270+ -- Weights are almost random
271+ -- Uniform oneof tends not to build complex objects cause of recursive call.
272+ arbitrary = resize 4 $ frequency
273+ [ (3, Object <$> arbitrary)
274+ , (3, Array <$> arbitrary)
275+ , (3, String <$> arbitrary)
276+ , (3, Number <$> arbitrary)
277+ , (3, Bool <$> arbitrary)
278+ , (1, return Null) ]
test/Data/Swagger/SchemaSpec.hs+25−513
@@ -7,22 +7,23 @@ module Data.Swagger.SchemaSpec where
77import Prelude ()
88import Prelude.Compat
99
10−import Data.Aeson
11−import Data.Aeson.QQ
12−import Data.Char
13−import qualified Data.HashMap.Strict as HashMap
10+import Control.Lens ((^.))
11+import Data.Aeson (Value)
12+import qualified Data.HashMap.Strict.InsOrd as InsOrdHashMap
1413import Data.Proxy
1514import Data.Set (Set)
16−import qualified Data.Set as Set
1715import qualified Data.Text as Text
18−import GHC.Generics
1916
2017import Data.Swagger
2118import Data.Swagger.Declare
2219
20+import Data.Swagger.CommonTestTypes
2321import SpecCommon
2422import Test.Hspec
2523
24+import qualified Data.HashMap.Strict as HM
25+import Data.Time.LocalTime
26+
2627checkToSchema :: ToSchema a => Proxy a -> Value -> Spec
2728checkToSchema proxy js = toSchema proxy <=> js
2829
@@ -34,10 +35,17 @@ checkSchemaName sname proxy =
3435checkDefs :: ToSchema a => Proxy a -> [String] -> Spec
3536checkDefs proxy names =
3637 it ("uses these definitions " ++ show names) $
37− Set.fromList (HashMap.keys defs) `shouldBe` Set.fromList (map Text.pack names)
38+ InsOrdHashMap.keys defs `shouldBe` map Text.pack names
3839 where
3940 defs = execDeclare (declareNamedSchema proxy) mempty
4041
42+checkProperties :: ToSchema a => Proxy a -> [String] -> Spec
43+checkProperties proxy names =
44+ it ("has these fields in order " ++ show names) $
45+ InsOrdHashMap.keys fields `shouldBe` map Text.pack names
46+ where
47+ fields = toSchema proxy ^. properties
48+
4149checkInlinedSchema :: ToSchema a => Proxy a -> Value -> Spec
4250checkInlinedSchema proxy js = toInlinedSchema proxy <=> js
4351
@@ -58,6 +66,9 @@ spec = do
5866 context "Person" $ checkToSchema (Proxy :: Proxy Person) personSchemaJSON
5967 context "ISPair" $ checkToSchema (Proxy :: Proxy ISPair) ispairSchemaJSON
6068 context "Point (fieldLabelModifier)" $ checkToSchema (Proxy :: Proxy Point) pointSchemaJSON
69+ context "Point5 (many field record)" $ do
70+ checkToSchema (Proxy :: Proxy Point5) point5SchemaJSON
71+ checkProperties (Proxy :: Proxy Point5) point5Properties
6172 context "Color (bounded enum)" $ checkToSchema (Proxy :: Proxy Color) colorSchemaJSON
6273 context "Shade (paramSchemaToNamedSchema)" $ checkToSchema (Proxy :: Proxy Shade) shadeSchemaJSON
6374 context "Paint (record with bounded enum field)" $ checkToSchema (Proxy :: Proxy Paint) paintSchemaJSON
@@ -66,8 +77,10 @@ spec = do
6677 context "Email (unwrapUnaryRecords)" $ checkToSchema (Proxy :: Proxy Email) emailSchemaJSON
6778 context "UserId (non-record newtype)" $ checkToSchema (Proxy :: Proxy UserId) userIdSchemaJSON
6879 context "Player (unary record)" $ checkToSchema (Proxy :: Proxy Player) playerSchemaJSON
80+ context "SingleMaybeField (unary record with Maybe)" $ checkToSchema (Proxy :: Proxy SingleMaybeField) singleMaybeFieldSchemaJSON
6981 context "Players (inlining schema)" $ checkToSchema (Proxy :: Proxy Players) playersSchemaJSON
7082 context "MyRoseTree (datatypeNameModifier)" $ checkToSchema (Proxy :: Proxy MyRoseTree) myRoseTreeSchemaJSON
83+ context "MyRoseTree' (datatypeNameModifier)" $ checkToSchema (Proxy :: Proxy MyRoseTree') myRoseTreeSchemaJSON'
7184 context "Sum types" $ do
7285 context "Status (sum of unary constructors)" $ checkToSchema (Proxy :: Proxy Status) statusSchemaJSON
7386 context "Character (ref and record sum)" $ checkToSchema (Proxy :: Proxy Character) characterSchemaJSON
@@ -83,6 +96,7 @@ spec = do
8396 context "Light" $ checkDefs (Proxy :: Proxy Light) ["Color"]
8497 context "Character" $ checkDefs (Proxy :: Proxy Character) ["Player", "Point"]
8598 context "MyRoseTree" $ checkDefs (Proxy :: Proxy MyRoseTree) ["RoseTree"]
99+ context "MyRoseTree'" $ checkDefs (Proxy :: Proxy MyRoseTree') ["myrosetree'"]
86100 context "[Set (Unit, Maybe Color)]" $ checkDefs (Proxy :: Proxy [Set (Unit, Maybe Color)]) ["Unit", "Color"]
87101 context "ResourceId" $ checkDefs (Proxy :: Proxy ResourceId) []
88102 describe "Inlining Schemas" $ do
@@ -91,512 +105,10 @@ spec = do
91105 context "Character (inlining only Player)" $ checkInlinedSchemas ["Player"] (Proxy :: Proxy Character) characterInlinedPlayerSchemaJSON
92106 context "Light" $ checkInlinedSchema (Proxy :: Proxy Light) lightInlinedSchemaJSON
93107 context "MyRoseTree (inlineNonRecursiveSchemas)" $ checkInlinedRecSchema (Proxy :: Proxy MyRoseTree) myRoseTreeSchemaJSON
108+ context "MyRoseTree' (inlineNonRecursiveSchemas)" $ checkInlinedRecSchema (Proxy :: Proxy MyRoseTree') myRoseTreeSchemaJSON'
109+ describe "Bounded Enum key mapping" $ do
110+ context "ButtonImages" $ checkToSchema (Proxy :: Proxy ButtonImages) buttonImagesSchemaJSON
111+ context "TimeOfDay" $ checkToSchema (Proxy :: Proxy Data.Time.LocalTime.TimeOfDay) timeOfDaySchemaJSON
94112
95113main :: IO ()
96114main = hspec spec
97−
98−-- ========================================================================
99−-- Person (simple record with optional fields)
100−-- ========================================================================
101−data Person = Person
102− { name :: String
103− , phone :: Integer
104− , email :: Maybe String
105− } deriving (Generic)
106−
107−instance ToSchema Person
108−
109−personSchemaJSON :: Value
110−personSchemaJSON = [aesonQQ|
111−{
112− "type": "object",
113− "properties":
114− {
115− "name": { "type": "string" },
116− "phone": { "type": "integer" },
117− "email": { "type": "string" }
118− },
119− "required": ["name", "phone"]
120−}
121−|]
122−
123−-- ========================================================================
124−-- ISPair (non-record product data type)
125−-- ========================================================================
126−data ISPair = ISPair Integer String
127− deriving (Generic)
128−
129−instance ToSchema ISPair
130−
131−ispairSchemaJSON :: Value
132−ispairSchemaJSON = [aesonQQ|
133−{
134− "type": "array",
135− "items":
136− [
137− { "type": "integer" },
138− { "type": "string" }
139− ]
140−}
141−|]
142−
143−-- ========================================================================
144−-- Point (record data type with custom fieldLabelModifier)
145−-- ========================================================================
146−data Point = Point
147− { pointX :: Double
148− , pointY :: Double
149− } deriving (Generic)
150−
151−instance ToSchema Point where
152− declareNamedSchema = genericDeclareNamedSchema defaultSchemaOptions
153− { fieldLabelModifier = map toLower . drop (length "point") }
154−
155−pointSchemaJSON :: Value
156−pointSchemaJSON = [aesonQQ|
157−{
158− "type": "object",
159− "properties":
160− {
161− "x": { "type": "number", "format": "double" },
162− "y": { "type": "number", "format": "double" }
163− },
164− "required": ["x", "y"]
165−}
166−|]
167−
168−
169−-- ========================================================================
170−-- Color (enum)
171−-- ========================================================================
172−data Color
173− = Red
174− | Green
175− | Blue
176− deriving (Generic)
177−instance ToSchema Color
178−
179−colorSchemaJSON :: Value
180−colorSchemaJSON = [aesonQQ|
181−{
182− "type": "string",
183− "enum": ["Red", "Green", "Blue"]
184−}
185−|]
186−
187−-- ========================================================================
188−-- Shade (paramSchemaToNamedSchema)
189−-- ========================================================================
190−
191−data Shade = Dim | Bright deriving (Generic)
192−instance ToParamSchema Shade
193−
194−instance ToSchema Shade where declareNamedSchema = pure . paramSchemaToNamedSchema defaultSchemaOptions
195−
196−shadeSchemaJSON :: Value
197−shadeSchemaJSON = [aesonQQ|
198−{
199− "type": "string",
200− "enum": ["Dim", "Bright"]
201−}
202−|]
203−
204−-- ========================================================================
205−-- Paint (record with bounded enum property)
206−-- ========================================================================
207−
208−newtype Paint = Paint { color :: Color }
209− deriving (Generic)
210−instance ToSchema Paint
211−
212−paintSchemaJSON :: Value
213−paintSchemaJSON = [aesonQQ|
214−{
215− "type": "object",
216− "properties":
217− {
218− "color":
219− {
220− "$ref": "#/definitions/Color"
221− }
222− },
223− "required": ["color"]
224−}
225−|]
226−
227−paintInlinedSchemaJSON :: Value
228−paintInlinedSchemaJSON = [aesonQQ|
229−{
230− "type": "object",
231− "properties":
232− {
233− "color":
234− {
235− "type": "string",
236− "enum": ["Red", "Green", "Blue"]
237− }
238− },
239− "required": ["color"]
240−}
241−|]
242−
243−-- ========================================================================
244−-- Email (newtype with unwrapUnaryRecords set to True)
245−-- ========================================================================
246−
247−newtype Email = Email { getEmail :: String }
248− deriving (Generic)
249−
250−instance ToSchema Email where
251− declareNamedSchema = genericDeclareNamedSchema defaultSchemaOptions
252− { unwrapUnaryRecords = True }
253−
254−emailSchemaJSON :: Value
255−emailSchemaJSON = [aesonQQ|
256−{
257− "type": "string"
258−}
259−|]
260−
261−-- ========================================================================
262−-- UserId (non-record newtype)
263−-- ========================================================================
264−
265−newtype UserId = UserId Integer
266− deriving (Eq, Ord, Generic)
267−instance ToSchema UserId
268−
269−userIdSchemaJSON :: Value
270−userIdSchemaJSON = [aesonQQ|
271−{
272− "type": "integer"
273−}
274−|]
275−
276−-- ========================================================================
277−-- UserGroup (set newtype)
278−-- ========================================================================
279−
280−newtype UserGroup = UserGroup (Set UserId)
281− deriving (Generic)
282−instance ToSchema UserGroup
283−
284−userGroupSchemaJSON :: Value
285−userGroupSchemaJSON = [aesonQQ|
286−{
287− "type": "array",
288− "items": { "$ref": "#/definitions/UserId" },
289− "uniqueItems": true
290−}
291−|]
292−
293−-- ========================================================================
294−-- Player (record newtype)
295−-- ========================================================================
296−
297−newtype Player = Player
298− { position :: Point
299− } deriving (Generic)
300−instance ToSchema Player
301−
302−playerSchemaJSON :: Value
303−playerSchemaJSON = [aesonQQ|
304−{
305− "type": "object",
306− "properties":
307− {
308− "position":
309− {
310− "$ref": "#/definitions/Point"
311− }
312− },
313− "required": ["position"]
314−}
315−|]
316−
317−-- ========================================================================
318−-- MyRoseTree (custom datatypeNameModifier)
319−-- ========================================================================
320−
321−data MyRoseTree = MyRoseTree
322− { root :: String
323− , trees :: [MyRoseTree]
324− } deriving (Generic)
325−
326−instance ToSchema MyRoseTree where
327− declareNamedSchema = genericDeclareNamedSchema defaultSchemaOptions
328− { datatypeNameModifier = drop (length "My") }
329−
330−myRoseTreeSchemaJSON :: Value
331−myRoseTreeSchemaJSON = [aesonQQ|
332−{
333− "type": "object",
334− "properties":
335− {
336− "root": { "type": "string" },
337− "trees":
338− {
339− "type": "array",
340− "items":
341− {
342− "$ref": "#/definitions/RoseTree"
343− }
344− }
345− },
346− "required": ["root", "trees"]
347−}
348−|]
349−
350−-- ========================================================================
351−-- Inlined (newtype for inlining schemas)
352−-- ========================================================================
353−
354−newtype Inlined a = Inlined { getInlined :: a }
355−
356−instance ToSchema a => ToSchema (Inlined a) where
357− declareNamedSchema _ = unname <$> declareNamedSchema (Proxy :: Proxy a)
358− where
359− unname (NamedSchema _ s) = NamedSchema Nothing s
360−
361−newtype Players = Players [Inlined Player]
362− deriving (Generic)
363−instance ToSchema Players
364−
365−playersSchemaJSON :: Value
366−playersSchemaJSON = [aesonQQ|
367−{
368− "type": "array",
369− "items":
370− {
371− "type": "object",
372− "properties":
373− {
374− "position":
375− {
376− "$ref": "#/definitions/Point"
377− }
378− },
379− "required": ["position"]
380− }
381−}
382−|]
383−
384−-- ========================================================================
385−-- Status (sum type with unary constructors)
386−-- ========================================================================
387−
388−data Status
389− = StatusOk String
390− | StatusError String
391− deriving (Generic)
392−
393−instance ToSchema Status where
394− declareNamedSchema = genericDeclareNamedSchema defaultSchemaOptions
395− { constructorTagModifier = map toLower . drop (length "Status") }
396−
397−statusSchemaJSON :: Value
398−statusSchemaJSON = [aesonQQ|
399−{
400− "type": "object",
401− "properties":
402− {
403− "ok": { "type": "string" },
404− "error": { "type": "string" }
405− },
406− "maxProperties": 1,
407− "minProperties": 1
408−}
409−|]
410−
411−-- ========================================================================
412−-- Unit type
413−-- ========================================================================
414−
415−data Unit = Unit deriving (Generic)
416−instance ToSchema Unit
417−
418−unitSchemaJSON :: Value
419−unitSchemaJSON = [aesonQQ|
420−{
421− "type": "string",
422− "enum": ["Unit"]
423−}
424−|]
425−
426−
427−-- ========================================================================
428−-- Character (sum type with ref and record in alternative)
429−-- ========================================================================
430−
431−data Character
432− = PC Player
433− | NPC { npcName :: String, npcPosition :: Point }
434− deriving (Generic)
435−instance ToSchema Character
436−
437−characterSchemaJSON :: Value
438−characterSchemaJSON = [aesonQQ|
439−{
440− "type": "object",
441− "properties":
442− {
443− "PC": { "$ref": "#/definitions/Player" },
444− "NPC":
445− {
446− "type": "object",
447− "properties":
448− {
449− "npcName": { "type": "string" },
450− "npcPosition": { "$ref": "#/definitions/Point" }
451− },
452− "required": ["npcName", "npcPosition"]
453− }
454− },
455− "maxProperties": 1,
456− "minProperties": 1
457−}
458−|]
459−
460−characterInlinedSchemaJSON :: Value
461−characterInlinedSchemaJSON = [aesonQQ|
462−{
463− "type": "object",
464− "properties":
465− {
466− "PC":
467− {
468− "type": "object",
469− "properties":
470− {
471− "position":
472− {
473− "type": "object",
474− "properties":
475− {
476− "x": { "type": "number", "format": "double" },
477− "y": { "type": "number", "format": "double" }
478− },
479− "required": ["x", "y"]
480− }
481− },
482− "required": ["position"]
483− },
484− "NPC":
485− {
486− "type": "object",
487− "properties":
488− {
489− "npcName": { "type": "string" },
490− "npcPosition":
491− {
492− "type": "object",
493− "properties":
494− {
495− "x": { "type": "number", "format": "double" },
496− "y": { "type": "number", "format": "double" }
497− },
498− "required": ["x", "y"]
499− }
500− },
501− "required": ["npcName", "npcPosition"]
502− }
503− },
504− "maxProperties": 1,
505− "minProperties": 1
506−}
507−|]
508−
509−characterInlinedPlayerSchemaJSON :: Value
510−characterInlinedPlayerSchemaJSON = [aesonQQ|
511−{
512− "type": "object",
513− "properties":
514− {
515− "PC":
516− {
517− "type": "object",
518− "properties":
519− {
520− "position":
521− {
522− "$ref": "#/definitions/Point"
523− }
524− },
525− "required": ["position"]
526− },
527− "NPC":
528− {
529− "type": "object",
530− "properties":
531− {
532− "npcName": { "type": "string" },
533− "npcPosition": { "$ref": "#/definitions/Point" }
534− },
535− "required": ["npcName", "npcPosition"]
536− }
537− },
538− "maxProperties": 1,
539− "minProperties": 1
540−}
541−|]
542−
543−-- ========================================================================
544−-- Light (sum type with unwrapUnaryRecords)
545−-- ========================================================================
546−
547−data Light
548− = NoLight
549− | LightFreq Double
550− | LightColor Color
551− | LightWaveLength { waveLength :: Double }
552− deriving (Generic)
553−
554−instance ToSchema Light where
555− declareNamedSchema = genericDeclareNamedSchema defaultSchemaOptions
556− { unwrapUnaryRecords = True }
557−
558−lightSchemaJSON :: Value
559−lightSchemaJSON = [aesonQQ|
560−{
561− "type": "object",
562− "properties":
563− {
564− "NoLight": { "type": "array", "items": [] },
565− "LightFreq": { "type": "number", "format": "double" },
566− "LightColor": { "$ref": "#/definitions/Color" },
567− "LightWaveLength": { "type": "number", "format": "double" }
568− },
569− "maxProperties": 1,
570− "minProperties": 1
571−}
572−|]
573−
574−lightInlinedSchemaJSON :: Value
575−lightInlinedSchemaJSON = [aesonQQ|
576−{
577− "type": "object",
578− "properties":
579− {
580− "NoLight": { "type": "array", "items": [] },
581− "LightFreq": { "type": "number", "format": "double" },
582− "LightColor":
583− {
584− "type": "string",
585− "enum": ["Red", "Green", "Blue"]
586− },
587− "LightWaveLength": { "type": "number", "format": "double" }
588− },
589− "maxProperties": 1,
590− "minProperties": 1
591−}
592−|]
593−
594−-- ========================================================================
595−-- ResourceId (series of newtypes)
596−-- ========================================================================
597−
598−newtype Id = Id String deriving (Generic)
599−instance ToSchema Id
600−
601−newtype ResourceId = ResourceId Id deriving (Generic)
602−instance ToSchema ResourceId
test/Data/SwaggerSpec.hs+426−330
@@ -10,8 +10,9 @@ import Prelude.Compat
1010import Control.Lens
1111
1212import Data.Aeson
13−import Data.Aeson.QQ
13+import Data.Aeson.QQ.Simple
1414import Data.HashMap.Strict (HashMap)
15+import qualified Data.HashSet.InsOrd as InsOrdHS
1516import Data.Text (Text)
1617
1718import Data.Swagger
@@ -20,6 +21,14 @@ import Test.Hspec hiding (example)
2021
2122spec :: Spec
2223spec = do
24+ describe "host" $ do
25+ it "can decode the host port" $ do
26+ let h = Just $ Host "localhost" (Just (fromInteger 8000))
27+ swagger :: Swagger
28+ swagger = swaggerExample
29+ & host .~ h
30+ parsed :: Swagger = either error id $ eitherDecode' $ encode swagger
31+ parsed ^. host `shouldBe` h
2332 describe "License Object" $ licenseExample <=> licenseExampleJSON
2433 describe "Contact Object" $ contactExample <=> contactExampleJSON
2534 describe "Info Object" $ infoExample <=> infoExampleJSON
@@ -28,11 +37,14 @@ spec = do
2837 context "Primitive Sample" $ schemaPrimitiveExample <=> schemaPrimitiveExampleJSON
2938 context "Simple Model" $ schemaSimpleModelExample <=> schemaSimpleModelExampleJSON
3039 context "Model with Map/Dictionary Properties" $ schemaModelDictExample <=> schemaModelDictExampleJSON
40+ context "Model with Arbitrary Properties" $ schemaAdditionalExample <=> schemaAdditionalExampleJSON
3141 context "Model with Example" $ schemaWithExampleExample <=> schemaWithExampleExampleJSON
3242 describe "Definitions Object" $ definitionsExample <=> definitionsExampleJSON
3343 describe "Parameters Definition Object" $ paramsDefinitionExample <=> paramsDefinitionExampleJSON
3444 describe "Responses Definition Object" $ responsesDefinitionExample <=> responsesDefinitionExampleJSON
3545 describe "Security Definitions Object" $ securityDefinitionsExample <=> securityDefinitionsExampleJSON
46+ describe "OAuth2 Security Definitions with merged Scope" $ oAuth2SecurityDefinitionsExample <=> oAuth2SecurityDefinitionsExampleJSON
47+ describe "Composition Schema Example" $ compositionSchemaExample <=> compositionSchemaExampleJSON
3648 describe "Swagger Object" $ do
3749 context "Todo Example" $ swaggerExample <=> swaggerExampleJSON
3850 context "PetStore Example" $
@@ -98,7 +110,8 @@ contactExampleJSON = [aesonQQ|
98110-- =======================================================================
99111
100112licenseExample :: License
101−licenseExample = License "Apache 2.0" (Just (URL "http://www.apache.org/licenses/LICENSE-2.0.html"))
113+licenseExample = "Apache 2.0"
114+ & url ?~ URL "http://www.apache.org/licenses/LICENSE-2.0.html"
102115
103116licenseExampleJSON :: Value
104117licenseExampleJSON = [aesonQQ|
@@ -115,7 +128,7 @@ licenseExampleJSON = [aesonQQ|
115128
116129operationExample :: Operation
117130operationExample = mempty
118− & tags .~ ["pet"]
131+ & tags .~ InsOrdHS.fromList ["pet"]
119132 & summary ?~ "Updates a pet in the store with form data"
120133 & description ?~ ""
121134 & operationId ?~ "updatePetWithForm"
@@ -139,15 +152,14 @@ operationExample = mempty
139152 & schema .~ ParamOther (stringSchema ParamFormData)
140153 ]
141154
142− & responses .~ (mempty & responses .~
143− [ (200, Inline (mempty & description .~ "Pet updated."))
144− , (405, Inline (mempty & description .~ "Invalid input")) ])
155+ & at 200 ?~ "Pet updated."
156+ & at 405 ?~ "Invalid input"
145157 & security .~ [SecurityRequirement [("petstore_auth", ["write:pets", "read:pets"])]]
146158 where
147159 stringSchema :: ParamLocation -> ParamOtherSchema
148160 stringSchema loc = mempty
149161 & in_ .~ loc
150− & type_ .~ SwaggerString
162+ & type_ ?~ SwaggerString
151163
152164operationExampleJSON :: Value
153165operationExampleJSON = [aesonQQ|
@@ -213,7 +225,7 @@ operationExampleJSON = [aesonQQ|
213225
214226schemaPrimitiveExample :: Schema
215227schemaPrimitiveExample = mempty
216− & type_ .~ SwaggerString
228+ & type_ ?~ SwaggerString
217229 & format ?~ "email"
218230
219231schemaPrimitiveExampleJSON :: Value
@@ -226,14 +238,14 @@ schemaPrimitiveExampleJSON = [aesonQQ|
226238
227239schemaSimpleModelExample :: Schema
228240schemaSimpleModelExample = mempty
229− & type_ .~ SwaggerObject
241+ & type_ ?~ SwaggerObject
230242 & required .~ [ "name" ]
231243 & properties .~
232− [ ("name", Inline (mempty & type_ .~ SwaggerString))
244+ [ ("name", Inline (mempty & type_ ?~ SwaggerString))
233245 , ("address", Ref (Reference "Address"))
234246 , ("age", Inline $ mempty
235247 & minimum_ ?~ 0
236− & type_ .~ SwaggerInteger
248+ & type_ ?~ SwaggerInteger
237249 & format ?~ "int32" ) ]
238250
239251schemaSimpleModelExampleJSON :: Value
@@ -261,8 +273,8 @@ schemaSimpleModelExampleJSON = [aesonQQ|
261273
262274schemaModelDictExample :: Schema
263275schemaModelDictExample = mempty
264− & type_ .~ SwaggerObject
265− & additionalProperties ?~ (mempty & type_ .~ SwaggerString)
276+ & type_ ?~ SwaggerObject
277+ & additionalProperties ?~ AdditionalPropertiesSchema (Inline (mempty & type_ ?~ SwaggerString))
266278
267279schemaModelDictExampleJSON :: Value
268280schemaModelDictExampleJSON = [aesonQQ|
@@ -274,15 +286,28 @@ schemaModelDictExampleJSON = [aesonQQ|
274286}
275287|]
276288
289+schemaAdditionalExample :: Schema
290+schemaAdditionalExample = mempty
291+ & type_ ?~ SwaggerObject
292+ & additionalProperties ?~ AdditionalPropertiesAllowed True
293+
294+schemaAdditionalExampleJSON :: Value
295+schemaAdditionalExampleJSON = [aesonQQ|
296+{
297+ "type": "object",
298+ "additionalProperties": true
299+}
300+|]
301+
277302schemaWithExampleExample :: Schema
278303schemaWithExampleExample = mempty
279− & type_ .~ SwaggerObject
304+ & type_ ?~ SwaggerObject
280305 & properties .~
281306 [ ("id", Inline $ mempty
282− & type_ .~ SwaggerInteger
307+ & type_ ?~ SwaggerInteger
283308 & format ?~ "int64" )
284309 , ("name", Inline $ mempty
285− & type_ .~ SwaggerString) ]
310+ & type_ ?~ SwaggerString) ]
286311 & required .~ [ "name" ]
287312 & example ?~ [aesonQQ|
288313 {
@@ -321,19 +346,19 @@ schemaWithExampleExampleJSON = [aesonQQ|
321346definitionsExample :: HashMap Text Schema
322347definitionsExample =
323348 [ ("Category", mempty
324− & type_ .~ SwaggerObject
349+ & type_ ?~ SwaggerObject
325350 & properties .~
326351 [ ("id", Inline $ mempty
327− & type_ .~ SwaggerInteger
352+ & type_ ?~ SwaggerInteger
328353 & format ?~ "int64")
329− , ("name", Inline (mempty & type_ .~ SwaggerString)) ] )
354+ , ("name", Inline (mempty & type_ ?~ SwaggerString)) ] )
330355 , ("Tag", mempty
331− & type_ .~ SwaggerObject
356+ & type_ ?~ SwaggerObject
332357 & properties .~
333358 [ ("id", Inline $ mempty
334− & type_ .~ SwaggerInteger
359+ & type_ ?~ SwaggerInteger
335360 & format ?~ "int64")
336− , ("name", Inline (mempty & type_ .~ SwaggerString)) ] ) ]
361+ , ("name", Inline (mempty & type_ ?~ SwaggerString)) ] ) ]
337362
338363definitionsExampleJSON :: Value
339364definitionsExampleJSON = [aesonQQ|
@@ -377,7 +402,7 @@ paramsDefinitionExample =
377402 & required ?~ True
378403 & schema .~ ParamOther (mempty
379404 & in_ .~ ParamQuery
380− & type_ .~ SwaggerInteger
405+ & type_ ?~ SwaggerInteger
381406 & format ?~ "int32" ))
382407 , ("limitParam", mempty
383408 & name .~ "limit"
@@ -385,7 +410,7 @@ paramsDefinitionExample =
385410 & required ?~ True
386411 & schema .~ ParamOther (mempty
387412 & in_ .~ ParamQuery
388− & type_ .~ SwaggerInteger
413+ & type_ ?~ SwaggerInteger
389414 & format ?~ "int32" )) ]
390415
391416paramsDefinitionExampleJSON :: Value
@@ -435,8 +460,8 @@ responsesDefinitionExampleJSON = [aesonQQ|
435460-- Responses Definition object
436461-- =======================================================================
437462
438−securityDefinitionsExample :: HashMap Text SecurityScheme
439−securityDefinitionsExample =
463+securityDefinitionsExample :: SecurityDefinitions
464+securityDefinitionsExample = SecurityDefinitions
440465 [ ("api_key", SecurityScheme
441466 { _securitySchemeType = SecuritySchemeApiKey (ApiKeyParams "api_key" ApiKeyHeader)
442467 , _securitySchemeDescription = Nothing })
@@ -468,6 +493,46 @@ securityDefinitionsExampleJSON = [aesonQQ|
468493}
469494|]
470495
496+oAuth2SecurityDefinitionsReadExample :: SecurityDefinitions
497+oAuth2SecurityDefinitionsReadExample = SecurityDefinitions
498+ [ ("petstore_auth", SecurityScheme
499+ { _securitySchemeType = SecuritySchemeOAuth2 (OAuth2Params
500+ { _oauth2Flow = OAuth2Implicit "http://swagger.io/api/oauth/dialog"
501+ , _oauth2Scopes =
502+ [ ("read:pets", "read your pets") ] } )
503+ , _securitySchemeDescription = Nothing })
504+ ]
505+
506+oAuth2SecurityDefinitionsWriteExample :: SecurityDefinitions
507+oAuth2SecurityDefinitionsWriteExample = SecurityDefinitions
508+ [ ("petstore_auth", SecurityScheme
509+ { _securitySchemeType = SecuritySchemeOAuth2 (OAuth2Params
510+ { _oauth2Flow = OAuth2Implicit "http://swagger.io/api/oauth/dialog"
511+ , _oauth2Scopes =
512+ [ ("write:pets", "modify pets in your account") ] } )
513+ , _securitySchemeDescription = Nothing })
514+ ]
515+
516+oAuth2SecurityDefinitionsExample :: SecurityDefinitions
517+oAuth2SecurityDefinitionsExample =
518+ oAuth2SecurityDefinitionsWriteExample <>
519+ oAuth2SecurityDefinitionsReadExample
520+
521+oAuth2SecurityDefinitionsExampleJSON :: Value
522+oAuth2SecurityDefinitionsExampleJSON = [aesonQQ|
523+{
524+ "petstore_auth": {
525+ "type": "oauth2",
526+ "authorizationUrl": "http://swagger.io/api/oauth/dialog",
527+ "flow": "implicit",
528+ "scopes": {
529+ "write:pets": "modify pets in your account",
530+ "read:pets": "read your pets"
531+ }
532+ }
533+}
534+|]
535+
471536-- =======================================================================
472537-- Swagger object
473538-- =======================================================================
@@ -479,24 +544,25 @@ swaggerExample = mempty
479544 & info .~ (mempty
480545 & version .~ "1.0"
481546 & title .~ "Todo API"
482− & license ?~ License "MIT" (Just (URL "http://mit.com"))
547+ & license ?~ "MIT"
548+ & license._Just.url ?~ URL "http://mit.com"
483549 & description ?~ "This is a an API that tests servant-swagger support for a Todo API")
484550 & paths.at "/todo/{id}" ?~ (mempty & get ?~ ((mempty :: Operation)
485551 & at 200 ?~ Inline (mempty
486552 & description .~ "OK"
487553 & schema ?~ Inline (mempty
488− & type_ .~ SwaggerObject
554+ & type_ ?~ SwaggerObject
489555 & example ?~ [aesonQQ|
490556 {
491557 "created": 100,
492558 "description": "get milk"
493559 } |]
494− & description ?~ "This is some real Todo right here"
560+ & description ?~ "This is some real Todo right here"
495561 & properties .~
496562 [ ("created", Inline $ mempty
497− & type_ .~ SwaggerInteger
563+ & type_ ?~ SwaggerInteger
498564 & format ?~ "int32")
499− , ("description", Inline (mempty & type_ .~ SwaggerString))]))
565+ , ("description", Inline (mempty & type_ ?~ SwaggerString))]))
500566 & produces ?~ MimeList [ "application/json" ]
501567 & parameters .~
502568 [ Inline $ mempty
@@ -505,8 +571,8 @@ swaggerExample = mempty
505571 & description ?~ "TodoId param"
506572 & schema .~ ParamOther (mempty
507573 & in_ .~ ParamPath
508− & type_ .~ SwaggerString ) ]
509− & tags .~ [ "todo" ] ))
574+ & type_ ?~ SwaggerString ) ]
575+ & tags .~ InsOrdHS.fromList [ "todo" ] ))
510576
511577swaggerExampleJSON :: Value
512578swaggerExampleJSON = [aesonQQ|
@@ -573,130 +639,130 @@ swaggerExampleJSON = [aesonQQ|
573639
574640petstoreExampleJSON :: Value
575641petstoreExampleJSON = [aesonQQ|
576−{
642+{
577643 "swagger":"2.0",
578− "info":{
644+ "info":{
579645 "description":"This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key `special-key` to test the authorization filters.",
580646 "version":"1.0.0",
581647 "title":"Swagger Petstore",
582648 "termsOfService":"http://swagger.io/terms/",
583− "contact":{
649+ "contact":{
584650 "email":"apiteam@swagger.io"
585651 },
586− "license":{
652+ "license":{
587653 "name":"Apache 2.0",
588654 "url":"http://www.apache.org/licenses/LICENSE-2.0.html"
589655 }
590656 },
591657 "host":"petstore.swagger.io",
592658 "basePath":"/v2",
593− "tags":[
594− {
659+ "tags":[
660+ {
595661 "name":"pet",
596662 "description":"Everything about your Pets",
597− "externalDocs":{
663+ "externalDocs":{
598664 "description":"Find out more",
599665 "url":"http://swagger.io"
600666 }
601667 },
602− {
668+ {
603669 "name":"store",
604670 "description":"Access to Petstore orders"
605671 },
606− {
672+ {
607673 "name":"user",
608674 "description":"Operations about user",
609− "externalDocs":{
675+ "externalDocs":{
610676 "description":"Find out more about our store",
611677 "url":"http://swagger.io"
612678 }
613679 }
614680 ],
615− "schemes":[
681+ "schemes":[
616682 "http"
617683 ],
618− "paths":{
619− "/pet":{
620− "post":{
621− "tags":[
684+ "paths":{
685+ "/pet":{
686+ "post":{
687+ "tags":[
622688 "pet"
623689 ],
624690 "summary":"Add a new pet to the store",
625691 "description":"",
626692 "operationId":"addPet",
627− "consumes":[
693+ "consumes":[
628694 "application/json",
629695 "application/xml"
630696 ],
631− "produces":[
697+ "produces":[
632698 "application/xml",
633699 "application/json"
634700 ],
635− "parameters":[
636− {
701+ "parameters":[
702+ {
637703 "in":"body",
638704 "name":"body",
639705 "description":"Pet object that needs to be added to the store",
640706 "required":true,
641− "schema":{
707+ "schema":{
642708 "$ref":"#/definitions/Pet"
643709 }
644710 }
645711 ],
646− "responses":{
647− "405":{
712+ "responses":{
713+ "405":{
648714 "description":"Invalid input"
649715 }
650716 },
651− "security":[
652− {
653− "petstore_auth":[
717+ "security":[
718+ {
719+ "petstore_auth":[
654720 "write:pets",
655721 "read:pets"
656722 ]
657723 }
658724 ]
659725 },
660− "put":{
661− "tags":[
726+ "put":{
727+ "tags":[
662728 "pet"
663729 ],
664730 "summary":"Update an existing pet",
665731 "description":"",
666732 "operationId":"updatePet",
667− "consumes":[
733+ "consumes":[
668734 "application/json",
669735 "application/xml"
670736 ],
671− "produces":[
737+ "produces":[
672738 "application/xml",
673739 "application/json"
674740 ],
675− "parameters":[
676− {
741+ "parameters":[
742+ {
677743 "in":"body",
678744 "name":"body",
679745 "description":"Pet object that needs to be added to the store",
680746 "required":true,
681− "schema":{
747+ "schema":{
682748 "$ref":"#/definitions/Pet"
683749 }
684750 }
685751 ],
686− "responses":{
687− "400":{
752+ "responses":{
753+ "400":{
688754 "description":"Invalid ID supplied"
689755 },
690− "404":{
756+ "404":{
691757 "description":"Pet not found"
692758 },
693− "405":{
759+ "405":{
694760 "description":"Validation exception"
695761 }
696762 },
697− "security":[
698− {
699− "petstore_auth":[
763+ "security":[
764+ {
765+ "petstore_auth":[
700766 "write:pets",
701767 "read:pets"
702768 ]
@@ -704,28 +770,28 @@ petstoreExampleJSON = [aesonQQ|
704770 ]
705771 }
706772 },
707− "/pet/findByStatus":{
708− "get":{
709− "tags":[
773+ "/pet/findByStatus":{
774+ "get":{
775+ "tags":[
710776 "pet"
711777 ],
712778 "summary":"Finds Pets by status",
713779 "description":"Multiple status values can be provided with comma seperated strings",
714780 "operationId":"findPetsByStatus",
715− "produces":[
781+ "produces":[
716782 "application/xml",
717783 "application/json"
718784 ],
719− "parameters":[
720− {
785+ "parameters":[
786+ {
721787 "name":"status",
722788 "in":"query",
723789 "description":"Status values that need to be considered for filter",
724790 "required":true,
725791 "type":"array",
726− "items":{
792+ "items":{
727793 "type":"string",
728− "enum":[
794+ "enum":[
729795 "available",
730796 "pending",
731797 "sold"
@@ -735,23 +801,23 @@ petstoreExampleJSON = [aesonQQ|
735801 "collectionFormat":"csv"
736802 }
737803 ],
738− "responses":{
739− "200":{
804+ "responses":{
805+ "200":{
740806 "description":"successful operation",
741− "schema":{
807+ "schema":{
742808 "type":"array",
743− "items":{
809+ "items":{
744810 "$ref":"#/definitions/Pet"
745811 }
746812 }
747813 },
748− "400":{
814+ "400":{
749815 "description":"Invalid status value"
750816 }
751817 },
752− "security":[
753− {
754− "petstore_auth":[
818+ "security":[
819+ {
820+ "petstore_auth":[
755821 "write:pets",
756822 "read:pets"
757823 ]
@@ -759,48 +825,48 @@ petstoreExampleJSON = [aesonQQ|
759825 ]
760826 }
761827 },
762− "/pet/findByTags":{
763− "get":{
764− "tags":[
828+ "/pet/findByTags":{
829+ "get":{
830+ "tags":[
765831 "pet"
766832 ],
767833 "summary":"Finds Pets by tags",
768834 "description":"Muliple tags can be provided with comma seperated strings. Use tag1, tag2, tag3 for testing.",
769835 "operationId":"findPetsByTags",
770− "produces":[
836+ "produces":[
771837 "application/xml",
772838 "application/json"
773839 ],
774− "parameters":[
775− {
840+ "parameters":[
841+ {
776842 "name":"tags",
777843 "in":"query",
778844 "description":"Tags to filter by",
779845 "required":true,
780846 "type":"array",
781− "items":{
847+ "items":{
782848 "type":"string"
783849 },
784850 "collectionFormat":"csv"
785851 }
786852 ],
787− "responses":{
788− "200":{
853+ "responses":{
854+ "200":{
789855 "description":"successful operation",
790− "schema":{
856+ "schema":{
791857 "type":"array",
792− "items":{
858+ "items":{
793859 "$ref":"#/definitions/Pet"
794860 }
795861 }
796862 },
797− "400":{
863+ "400":{
798864 "description":"Invalid tag value"
799865 }
800866 },
801− "security":[
802− {
803− "petstore_auth":[
867+ "security":[
868+ {
869+ "petstore_auth":[
804870 "write:pets",
805871 "read:pets"
806872 ]
@@ -808,20 +874,20 @@ petstoreExampleJSON = [aesonQQ|
808874 ]
809875 }
810876 },
811− "/pet/{petId}":{
812− "get":{
813− "tags":[
877+ "/pet/{petId}":{
878+ "get":{
879+ "tags":[
814880 "pet"
815881 ],
816882 "summary":"Find pet by ID",
817883 "description":"Returns a single pet",
818884 "operationId":"getPetById",
819− "produces":[
885+ "produces":[
820886 "application/xml",
821887 "application/json"
822888 ],
823− "parameters":[
824− {
889+ "parameters":[
890+ {
825891 "name":"petId",
826892 "in":"path",
827893 "description":"ID of pet to return",
@@ -830,42 +896,42 @@ petstoreExampleJSON = [aesonQQ|
830896 "format":"int64"
831897 }
832898 ],
833− "responses":{
834− "200":{
899+ "responses":{
900+ "200":{
835901 "description":"successful operation",
836− "schema":{
902+ "schema":{
837903 "$ref":"#/definitions/Pet"
838904 }
839905 },
840− "400":{
906+ "400":{
841907 "description":"Invalid ID supplied"
842908 },
843− "404":{
909+ "404":{
844910 "description":"Pet not found"
845911 }
846912 },
847− "security":[
848− {
913+ "security":[
914+ {
849915 "api_key": []
850916 }
851917 ]
852918 },
853− "post":{
854− "tags":[
919+ "post":{
920+ "tags":[
855921 "pet"
856922 ],
857923 "summary":"Updates a pet in the store with form data",
858924 "description":"",
859925 "operationId":"updatePetWithForm",
860− "consumes":[
926+ "consumes":[
861927 "application/x-www-form-urlencoded"
862928 ],
863− "produces":[
929+ "produces":[
864930 "application/xml",
865931 "application/json"
866932 ],
867− "parameters":[
868− {
933+ "parameters":[
934+ {
869935 "name":"petId",
870936 "in":"path",
871937 "description":"ID of pet that needs to be updated",
@@ -873,14 +939,14 @@ petstoreExampleJSON = [aesonQQ|
873939 "type":"integer",
874940 "format":"int64"
875941 },
876− {
942+ {
877943 "name":"name",
878944 "in":"formData",
879945 "description":"Updated name of the pet",
880946 "required":false,
881947 "type":"string"
882948 },
883− {
949+ {
884950 "name":"status",
885951 "in":"formData",
886952 "description":"Updated status of the pet",
@@ -888,39 +954,39 @@ petstoreExampleJSON = [aesonQQ|
888954 "type":"string"
889955 }
890956 ],
891− "responses":{
892− "405":{
957+ "responses":{
958+ "405":{
893959 "description":"Invalid input"
894960 }
895961 },
896− "security":[
897− {
898− "petstore_auth":[
962+ "security":[
963+ {
964+ "petstore_auth":[
899965 "write:pets",
900966 "read:pets"
901967 ]
902968 }
903969 ]
904970 },
905− "delete":{
906− "tags":[
971+ "delete":{
972+ "tags":[
907973 "pet"
908974 ],
909975 "summary":"Deletes a pet",
910976 "description":"",
911977 "operationId":"deletePet",
912− "produces":[
978+ "produces":[
913979 "application/xml",
914980 "application/json"
915981 ],
916− "parameters":[
917− {
982+ "parameters":[
983+ {
918984 "name":"api_key",
919985 "in":"header",
920986 "required":false,
921987 "type":"string"
922988 },
923− {
989+ {
924990 "name":"petId",
925991 "in":"path",
926992 "description":"Pet id to delete",
@@ -929,14 +995,14 @@ petstoreExampleJSON = [aesonQQ|
929995 "format":"int64"
930996 }
931997 ],
932− "responses":{
933− "400":{
998+ "responses":{
999+ "400":{
9341000 "description":"Invalid pet value"
9351001 }
9361002 },
937− "security":[
938− {
939− "petstore_auth":[
1003+ "security":[
1004+ {
1005+ "petstore_auth":[
9401006 "write:pets",
9411007 "read:pets"
9421008 ]
@@ -944,22 +1010,22 @@ petstoreExampleJSON = [aesonQQ|
9441010 ]
9451011 }
9461012 },
947− "/pet/{petId}/uploadImage":{
948− "post":{
949− "tags":[
1013+ "/pet/{petId}/uploadImage":{
1014+ "post":{
1015+ "tags":[
9501016 "pet"
9511017 ],
9521018 "summary":"uploads an image",
9531019 "description":"",
9541020 "operationId":"uploadFile",
955− "consumes":[
1021+ "consumes":[
9561022 "multipart/form-data"
9571023 ],
958− "produces":[
1024+ "produces":[
9591025 "application/json"
9601026 ],
961− "parameters":[
962− {
1027+ "parameters":[
1028+ {
9631029 "name":"petId",
9641030 "in":"path",
9651031 "description":"ID of pet to update",
@@ -967,14 +1033,14 @@ petstoreExampleJSON = [aesonQQ|
9671033 "type":"integer",
9681034 "format":"int64"
9691035 },
970− {
1036+ {
9711037 "name":"additionalMetadata",
9721038 "in":"formData",
9731039 "description":"Additional data to pass to server",
9741040 "required":false,
9751041 "type":"string"
9761042 },
977− {
1043+ {
9781044 "name":"file",
9791045 "in":"formData",
9801046 "description":"file to upload",
@@ -982,17 +1048,17 @@ petstoreExampleJSON = [aesonQQ|
9821048 "type":"file"
9831049 }
9841050 ],
985− "responses":{
986− "200":{
1051+ "responses":{
1052+ "200":{
9871053 "description":"successful operation",
988− "schema":{
1054+ "schema":{
9891055 "$ref":"#/definitions/ApiResponse"
9901056 }
9911057 }
9921058 },
993− "security":[
994− {
995− "petstore_auth":[
1059+ "security":[
1060+ {
1061+ "petstore_auth":[
9961062 "write:pets",
9971063 "read:pets"
9981064 ]
@@ -1000,87 +1066,87 @@ petstoreExampleJSON = [aesonQQ|
10001066 ]
10011067 }
10021068 },
1003− "/store/inventory":{
1004− "get":{
1005− "tags":[
1069+ "/store/inventory":{
1070+ "get":{
1071+ "tags":[
10061072 "store"
10071073 ],
10081074 "summary":"Returns pet inventories by status",
10091075 "description":"Returns a map of status codes to quantities",
10101076 "operationId":"getInventory",
1011− "produces":[
1077+ "produces":[
10121078 "application/json"
10131079 ],
10141080 "parameters": [],
1015− "responses":{
1016− "200":{
1081+ "responses":{
1082+ "200":{
10171083 "description":"successful operation",
1018− "schema":{
1084+ "schema":{
10191085 "type":"object",
1020− "additionalProperties":{
1086+ "additionalProperties":{
10211087 "type":"integer",
10221088 "format":"int32"
10231089 }
10241090 }
10251091 }
10261092 },
1027− "security":[
1028− {
1093+ "security":[
1094+ {
10291095 "api_key": []
10301096 }
10311097 ]
10321098 }
10331099 },
1034− "/store/order":{
1035− "post":{
1036− "tags":[
1100+ "/store/order":{
1101+ "post":{
1102+ "tags":[
10371103 "store"
10381104 ],
10391105 "summary":"Place an order for a pet",
10401106 "description":"",
10411107 "operationId":"placeOrder",
1042− "produces":[
1108+ "produces":[
10431109 "application/xml",
10441110 "application/json"
10451111 ],
1046− "parameters":[
1047− {
1112+ "parameters":[
1113+ {
10481114 "in":"body",
10491115 "name":"body",
10501116 "description":"order placed for purchasing the pet",
10511117 "required":true,
1052− "schema":{
1118+ "schema":{
10531119 "$ref":"#/definitions/Order"
10541120 }
10551121 }
10561122 ],
1057− "responses":{
1058− "200":{
1123+ "responses":{
1124+ "200":{
10591125 "description":"successful operation",
1060− "schema":{
1126+ "schema":{
10611127 "$ref":"#/definitions/Order"
10621128 }
10631129 },
1064− "400":{
1130+ "400":{
10651131 "description":"Invalid Order"
10661132 }
10671133 }
10681134 }
10691135 },
1070− "/store/order/{orderId}":{
1071− "get":{
1072− "tags":[
1136+ "/store/order/{orderId}":{
1137+ "get":{
1138+ "tags":[
10731139 "store"
10741140 ],
10751141 "summary":"Find purchase order by ID",
10761142 "description":"For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",
10771143 "operationId":"getOrderById",
1078− "produces":[
1144+ "produces":[
10791145 "application/xml",
10801146 "application/json"
10811147 ],
1082− "parameters":[
1083− {
1148+ "parameters":[
1149+ {
10841150 "name":"orderId",
10851151 "in":"path",
10861152 "description":"ID of pet that needs to be fetched",
@@ -1091,34 +1157,34 @@ petstoreExampleJSON = [aesonQQ|
10911157 "format":"int64"
10921158 }
10931159 ],
1094− "responses":{
1095− "200":{
1160+ "responses":{
1161+ "200":{
10961162 "description":"successful operation",
1097− "schema":{
1163+ "schema":{
10981164 "$ref":"#/definitions/Order"
10991165 }
11001166 },
1101− "400":{
1167+ "400":{
11021168 "description":"Invalid ID supplied"
11031169 },
1104− "404":{
1170+ "404":{
11051171 "description":"Order not found"
11061172 }
11071173 }
11081174 },
1109− "delete":{
1110− "tags":[
1175+ "delete":{
1176+ "tags":[
11111177 "store"
11121178 ],
11131179 "summary":"Delete purchase order by ID",
11141180 "description":"For valid response try integer IDs with value < 1000. Anything above 1000 or nonintegers will generate API errors",
11151181 "operationId":"deleteOrder",
1116− "produces":[
1182+ "produces":[
11171183 "application/xml",
11181184 "application/json"
11191185 ],
1120− "parameters":[
1121− {
1186+ "parameters":[
1187+ {
11221188 "name":"orderId",
11231189 "in":"path",
11241190 "description":"ID of the order that needs to be deleted",
@@ -1127,133 +1193,133 @@ petstoreExampleJSON = [aesonQQ|
11271193 "minimum":1.0
11281194 }
11291195 ],
1130− "responses":{
1131− "400":{
1196+ "responses":{
1197+ "400":{
11321198 "description":"Invalid ID supplied"
11331199 },
1134− "404":{
1200+ "404":{
11351201 "description":"Order not found"
11361202 }
11371203 }
11381204 }
11391205 },
1140− "/user":{
1141− "post":{
1142− "tags":[
1206+ "/user":{
1207+ "post":{
1208+ "tags":[
11431209 "user"
11441210 ],
11451211 "summary":"Create user",
11461212 "description":"This can only be done by the logged in user.",
11471213 "operationId":"createUser",
1148− "produces":[
1214+ "produces":[
11491215 "application/xml",
11501216 "application/json"
11511217 ],
1152− "parameters":[
1153− {
1218+ "parameters":[
1219+ {
11541220 "in":"body",
11551221 "name":"body",
11561222 "description":"Created user object",
11571223 "required":true,
1158− "schema":{
1224+ "schema":{
11591225 "$ref":"#/definitions/User"
11601226 }
11611227 }
11621228 ],
1163− "responses":{
1164− "default":{
1229+ "responses":{
1230+ "default":{
11651231 "description":"successful operation"
11661232 }
11671233 }
11681234 }
11691235 },
1170− "/user/createWithArray":{
1171− "post":{
1172− "tags":[
1236+ "/user/createWithArray":{
1237+ "post":{
1238+ "tags":[
11731239 "user"
11741240 ],
11751241 "summary":"Creates list of users with given input array",
11761242 "description":"",
11771243 "operationId":"createUsersWithArrayInput",
1178− "produces":[
1244+ "produces":[
11791245 "application/xml",
11801246 "application/json"
11811247 ],
1182− "parameters":[
1183− {
1248+ "parameters":[
1249+ {
11841250 "in":"body",
11851251 "name":"body",
11861252 "description":"List of user object",
11871253 "required":true,
1188− "schema":{
1254+ "schema":{
11891255 "type":"array",
1190− "items":{
1256+ "items":{
11911257 "$ref":"#/definitions/User"
11921258 }
11931259 }
11941260 }
11951261 ],
1196− "responses":{
1197− "default":{
1262+ "responses":{
1263+ "default":{
11981264 "description":"successful operation"
11991265 }
12001266 }
12011267 }
12021268 },
1203− "/user/createWithList":{
1204− "post":{
1205− "tags":[
1269+ "/user/createWithList":{
1270+ "post":{
1271+ "tags":[
12061272 "user"
12071273 ],
12081274 "summary":"Creates list of users with given input array",
12091275 "description":"",
12101276 "operationId":"createUsersWithListInput",
1211− "produces":[
1277+ "produces":[
12121278 "application/xml",
12131279 "application/json"
12141280 ],
1215− "parameters":[
1216− {
1281+ "parameters":[
1282+ {
12171283 "in":"body",
12181284 "name":"body",
12191285 "description":"List of user object",
12201286 "required":true,
1221− "schema":{
1287+ "schema":{
12221288 "type":"array",
1223− "items":{
1289+ "items":{
12241290 "$ref":"#/definitions/User"
12251291 }
12261292 }
12271293 }
12281294 ],
1229− "responses":{
1230− "default":{
1295+ "responses":{
1296+ "default":{
12311297 "description":"successful operation"
12321298 }
12331299 }
12341300 }
12351301 },
1236− "/user/login":{
1237− "get":{
1238− "tags":[
1302+ "/user/login":{
1303+ "get":{
1304+ "tags":[
12391305 "user"
12401306 ],
12411307 "summary":"Logs user into the system",
12421308 "description":"",
12431309 "operationId":"loginUser",
1244− "produces":[
1310+ "produces":[
12451311 "application/xml",
12461312 "application/json"
12471313 ],
1248− "parameters":[
1249− {
1314+ "parameters":[
1315+ {
12501316 "name":"username",
12511317 "in":"query",
12521318 "description":"The user name for login",
12531319 "required":true,
12541320 "type":"string"
12551321 },
1256− {
1322+ {
12571323 "name":"password",
12581324 "in":"query",
12591325 "description":"The password for login in clear text",
@@ -1261,65 +1327,65 @@ petstoreExampleJSON = [aesonQQ|
12611327 "type":"string"
12621328 }
12631329 ],
1264− "responses":{
1265− "200":{
1330+ "responses":{
1331+ "200":{
12661332 "description":"successful operation",
1267− "schema":{
1333+ "schema":{
12681334 "type":"string"
12691335 },
1270− "headers":{
1271− "X-Rate-Limit":{
1336+ "headers":{
1337+ "X-Rate-Limit":{
12721338 "type":"integer",
12731339 "format":"int32",
12741340 "description":"calls per hour allowed by the user"
12751341 },
1276− "X-Expires-After":{
1342+ "X-Expires-After":{
12771343 "type":"string",
12781344 "format":"date-time",
12791345 "description":"date in UTC when toekn expires"
12801346 }
12811347 }
12821348 },
1283− "400":{
1349+ "400":{
12841350 "description":"Invalid username/password supplied"
12851351 }
12861352 }
12871353 }
12881354 },
1289− "/user/logout":{
1290− "get":{
1291− "tags":[
1355+ "/user/logout":{
1356+ "get":{
1357+ "tags":[
12921358 "user"
12931359 ],
12941360 "summary":"Logs out current logged in user session",
12951361 "description":"",
12961362 "operationId":"logoutUser",
1297− "produces":[
1363+ "produces":[
12981364 "application/xml",
12991365 "application/json"
13001366 ],
13011367 "parameters": [],
1302− "responses":{
1303− "default":{
1368+ "responses":{
1369+ "default":{
13041370 "description":"successful operation"
13051371 }
13061372 }
13071373 }
13081374 },
1309− "/user/{username}":{
1310− "get":{
1311− "tags":[
1375+ "/user/{username}":{
1376+ "get":{
1377+ "tags":[
13121378 "user"
13131379 ],
13141380 "summary":"Get user by user name",
13151381 "description":"",
13161382 "operationId":"getUserByName",
1317− "produces":[
1383+ "produces":[
13181384 "application/xml",
13191385 "application/json"
13201386 ],
1321− "parameters":[
1322− {
1387+ "parameters":[
1388+ {
13231389 "name":"username",
13241390 "in":"path",
13251391 "description":"The name that needs to be fetched. Use user1 for testing. ",
@@ -1327,72 +1393,72 @@ petstoreExampleJSON = [aesonQQ|
13271393 "type":"string"
13281394 }
13291395 ],
1330− "responses":{
1331− "200":{
1396+ "responses":{
1397+ "200":{
13321398 "description":"successful operation",
1333− "schema":{
1399+ "schema":{
13341400 "$ref":"#/definitions/User"
13351401 }
13361402 },
1337− "400":{
1403+ "400":{
13381404 "description":"Invalid username supplied"
13391405 },
1340− "404":{
1406+ "404":{
13411407 "description":"User not found"
13421408 }
13431409 }
13441410 },
1345− "put":{
1346− "tags":[
1411+ "put":{
1412+ "tags":[
13471413 "user"
13481414 ],
13491415 "summary":"Updated user",
13501416 "description":"This can only be done by the logged in user.",
13511417 "operationId":"updateUser",
1352− "produces":[
1418+ "produces":[
13531419 "application/xml",
13541420 "application/json"
13551421 ],
1356− "parameters":[
1357− {
1422+ "parameters":[
1423+ {
13581424 "name":"username",
13591425 "in":"path",
13601426 "description":"name that need to be deleted",
13611427 "required":true,
13621428 "type":"string"
13631429 },
1364− {
1430+ {
13651431 "in":"body",
13661432 "name":"body",
13671433 "description":"Updated user object",
13681434 "required":true,
1369− "schema":{
1435+ "schema":{
13701436 "$ref":"#/definitions/User"
13711437 }
13721438 }
13731439 ],
1374− "responses":{
1375− "400":{
1440+ "responses":{
1441+ "400":{
13761442 "description":"Invalid user supplied"
13771443 },
1378− "404":{
1444+ "404":{
13791445 "description":"User not found"
13801446 }
13811447 }
13821448 },
1383− "delete":{
1384− "tags":[
1449+ "delete":{
1450+ "tags":[
13851451 "user"
13861452 ],
13871453 "summary":"Delete user",
13881454 "description":"This can only be done by the logged in user.",
13891455 "operationId":"deleteUser",
1390− "produces":[
1456+ "produces":[
13911457 "application/xml",
13921458 "application/json"
13931459 ],
1394− "parameters":[
1395− {
1460+ "parameters":[
1461+ {
13961462 "name":"username",
13971463 "in":"path",
13981464 "description":"The name that needs to be deleted",
@@ -1400,207 +1466,237 @@ petstoreExampleJSON = [aesonQQ|
14001466 "type":"string"
14011467 }
14021468 ],
1403− "responses":{
1404− "400":{
1469+ "responses":{
1470+ "400":{
14051471 "description":"Invalid username supplied"
14061472 },
1407− "404":{
1473+ "404":{
14081474 "description":"User not found"
14091475 }
14101476 }
14111477 }
14121478 }
14131479 },
1414− "securityDefinitions":{
1415− "petstore_auth":{
1480+ "securityDefinitions":{
1481+ "petstore_auth":{
14161482 "type":"oauth2",
14171483 "authorizationUrl":"http://petstore.swagger.io/api/oauth/dialog",
14181484 "flow":"implicit",
1419− "scopes":{
1485+ "scopes":{
14201486 "write:pets":"modify pets in your account",
14211487 "read:pets":"read your pets"
14221488 }
14231489 },
1424− "api_key":{
1490+ "api_key":{
14251491 "type":"apiKey",
14261492 "name":"api_key",
14271493 "in":"header"
14281494 }
14291495 },
1430− "definitions":{
1431− "Order":{
1496+ "definitions":{
1497+ "Order":{
14321498 "type":"object",
1433− "properties":{
1434− "id":{
1499+ "properties":{
1500+ "id":{
14351501 "type":"integer",
14361502 "format":"int64"
14371503 },
1438− "petId":{
1504+ "petId":{
14391505 "type":"integer",
14401506 "format":"int64"
14411507 },
1442− "quantity":{
1508+ "quantity":{
14431509 "type":"integer",
14441510 "format":"int32"
14451511 },
1446− "shipDate":{
1512+ "shipDate":{
14471513 "type":"string",
14481514 "format":"date-time"
14491515 },
1450− "status":{
1516+ "status":{
14511517 "type":"string",
14521518 "description":"Order Status",
1453− "enum":[
1519+ "enum":[
14541520 "placed",
14551521 "approved",
14561522 "delivered"
14571523 ]
14581524 },
1459− "complete":{
1525+ "complete":{
14601526 "type":"boolean",
14611527 "default":false
14621528 }
14631529 },
1464− "xml":{
1530+ "xml":{
14651531 "name":"Order"
14661532 }
14671533 },
1468− "Category":{
1534+ "Category":{
14691535 "type":"object",
1470− "properties":{
1471− "id":{
1536+ "properties":{
1537+ "id":{
14721538 "type":"integer",
14731539 "format":"int64"
14741540 },
1475− "name":{
1541+ "name":{
14761542 "type":"string"
14771543 }
14781544 },
1479− "xml":{
1545+ "xml":{
14801546 "name":"Category"
14811547 }
14821548 },
1483− "User":{
1549+ "User":{
14841550 "type":"object",
1485− "properties":{
1486− "id":{
1551+ "properties":{
1552+ "id":{
14871553 "type":"integer",
14881554 "format":"int64"
14891555 },
1490− "username":{
1556+ "username":{
14911557 "type":"string"
14921558 },
1493− "firstName":{
1559+ "firstName":{
14941560 "type":"string"
14951561 },
1496− "lastName":{
1562+ "lastName":{
14971563 "type":"string"
14981564 },
1499− "email":{
1565+ "email":{
15001566 "type":"string"
15011567 },
1502− "password":{
1568+ "password":{
15031569 "type":"string"
15041570 },
1505− "phone":{
1571+ "phone":{
15061572 "type":"string"
15071573 },
1508− "userStatus":{
1574+ "userStatus":{
15091575 "type":"integer",
15101576 "format":"int32",
15111577 "description":"User Status"
15121578 }
15131579 },
1514− "xml":{
1580+ "xml":{
15151581 "name":"User"
15161582 }
15171583 },
1518− "Tag":{
1584+ "Tag":{
15191585 "type":"object",
1520− "properties":{
1521− "id":{
1586+ "properties":{
1587+ "id":{
15221588 "type":"integer",
15231589 "format":"int64"
15241590 },
1525− "name":{
1591+ "name":{
15261592 "type":"string"
15271593 }
15281594 },
1529− "xml":{
1595+ "xml":{
15301596 "name":"Tag"
15311597 }
15321598 },
1533− "Pet":{
1599+ "Pet":{
15341600 "type":"object",
1535− "required":[
1601+ "required":[
15361602 "name",
15371603 "photoUrls"
15381604 ],
1539− "properties":{
1540− "id":{
1605+ "properties":{
1606+ "id":{
15411607 "type":"integer",
15421608 "format":"int64"
15431609 },
1544− "category":{
1610+ "category":{
15451611 "$ref":"#/definitions/Category"
15461612 },
1547− "name":{
1613+ "name":{
15481614 "type":"string",
15491615 "example":"doggie"
15501616 },
1551− "photoUrls":{
1617+ "photoUrls":{
15521618 "type":"array",
1553− "xml":{
1619+ "xml":{
15541620 "name":"photoUrl",
15551621 "wrapped":true
15561622 },
1557− "items":{
1623+ "items":{
15581624 "type":"string"
15591625 }
15601626 },
1561− "tags":{
1627+ "tags":{
15621628 "type":"array",
1563− "xml":{
1629+ "xml":{
15641630 "name":"tag",
15651631 "wrapped":true
15661632 },
1567− "items":{
1633+ "items":{
15681634 "$ref":"#/definitions/Tag"
15691635 }
15701636 },
1571− "status":{
1637+ "status":{
15721638 "type":"string",
15731639 "description":"pet status in the store",
1574− "enum":[
1640+ "enum":[
15751641 "available",
15761642 "pending",
15771643 "sold"
15781644 ]
15791645 }
15801646 },
1581− "xml":{
1647+ "xml":{
15821648 "name":"Pet"
15831649 }
15841650 },
1585− "ApiResponse":{
1651+ "ApiResponse":{
15861652 "type":"object",
1587− "properties":{
1588− "code":{
1653+ "properties":{
1654+ "code":{
15891655 "type":"integer",
15901656 "format":"int32"
15911657 },
1592− "type":{
1658+ "type":{
15931659 "type":"string"
15941660 },
1595− "message":{
1661+ "message":{
15961662 "type":"string"
15971663 }
15981664 }
15991665 }
16001666 },
1601− "externalDocs":{
1667+ "externalDocs":{
16021668 "description":"Find out more about Swagger",
16031669 "url":"http://swagger.io"
16041670 }
16051671}
16061672|]
1673+
1674+compositionSchemaExample :: Schema
1675+compositionSchemaExample = mempty
1676+ & type_ ?~ SwaggerObject
1677+ & Data.Swagger.allOf ?~ [
1678+ Ref (Reference "Other")
1679+ , Inline (mempty
1680+ & type_ ?~ SwaggerObject
1681+ & properties .~
1682+ [ ("greet", Inline $ mempty
1683+ & type_ ?~ SwaggerString) ])
1684+ ]
1685+
1686+compositionSchemaExampleJSON :: Value
1687+compositionSchemaExampleJSON = [aesonQQ|
1688+{
1689+ "type": "object",
1690+ "allOf": [
1691+ {
1692+ "$ref": "#/definitions/Other"
1693+ },
1694+ {
1695+ "type": "object",
1696+ "properties": {
1697+ "greet": { "type": "string" }
1698+ }
1699+ }
1700+ ]
1701+}
1702+|]
test/DocTest.hsdeleted−8
@@ -1,8 +0,0 @@
1−module Main (main) where
2−
3−import System.FilePath.Glob (glob)
4−import Test.DocTest (doctest)
5−
6−main :: IO ()
7−main = glob "src/**/*.hs" >>= doctest'
8− where doctest' files = doctest $ "-Iinclude/" : "-D__DOCTEST__" : files
test/SpecCommon.hs+7−2
@@ -1,6 +1,7 @@
11module SpecCommon where
22
33import Data.Aeson
4+import Data.ByteString.Builder (toLazyByteString)
45import qualified Data.Foldable as F
56import qualified Data.HashMap.Strict as HashMap
67import qualified Data.Vector as Vector
@@ -21,5 +22,9 @@ x <=> js = do
2122 toJSON x `shouldBe` js
2223 it "decodes correctly" $ do
2324 fromJSON js `shouldBe` Success x
24−
25−
25+ it "roundtrips: eitherDecode . encode" $ do
26+ eitherDecode (encode x) `shouldBe` Right x
27+ it "roundtrips with toJSON" $ do
28+ eitherDecode (encode $ toJSON x) `shouldBe` Right x
29+ it "roundtrips with toEncoding" $ do
30+ eitherDecode (toLazyByteString $ fromEncoding $ toEncoding x) `shouldBe` Right x
test/doctests.hsnew file+12
@@ -0,0 +1,12 @@
1+module Main where
2+
3+import Build_doctests (flags, pkgs, module_sources)
4+import Data.Foldable (traverse_)
5+import Test.DocTest
6+
7+main :: IO ()
8+main = do
9+ traverse_ putStrLn args
10+ doctest args
11+ where
12+ args = flags ++ pkgs ++ module_sources