git.iko.soy/typeable/swagger2
on master help sign in
swap
5470313307 ahead, 0 behind
39 files changed+5590−1531
since splitsnapshots
unifiedsplit
.ghci+2 .gitignore+2 .travis.yml+155−34 CHANGELOG.md+186−1 LICENSE+1−1 README.md+5−1 Setup.hs+31 cabal.project+2 examples/hackage.hs+40−24 hackage-docs.sh+78 include/overlapping-compat.h+8 src/Data/Swagger.hs+140−21 src/Data/Swagger/Declare.hs+91−10 src/Data/Swagger/Internal.hs+417−147 src/Data/Swagger/Internal/AesonUtils.hs+346 src/Data/Swagger/Internal/ParamSchema.hs+123−24 src/Data/Swagger/Internal/Schema.hs+413−97 src/Data/Swagger/Internal/Schema/Validation.hs+511 src/Data/Swagger/Internal/TypeShape.hs+66 src/Data/Swagger/Internal/Utils.hs+13−47 src/Data/Swagger/Lens.hs+87−59 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/Validation.hs+90 src/Data/Swagger/SchemaOptions.hs+35 stack.yaml+6−2 swagger2.cabal+107−34 test/Data/Swagger/CommonTestTypes.hs+679 test/Data/Swagger/ParamSchemaSpec.hs+10−82 test/Data/Swagger/Schema/GeneratorSpec.hs+168 test/Data/Swagger/Schema/ValidationSpec.hs+278 test/Data/Swagger/SchemaSpec.hs+32−501 test/Data/SwaggerSpec.hs+516−433 test/DocTest.hs−7 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+155−34
@@ -1,41 +1,162 @@
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+#
19language: c
2−
3−# explicitly request container-based infrastructure
4−sudo: false
5−
10+dist: xenial
11+git:
12+ # whether to recursively clone submodules
13+ submodules: false
14+branches:
15+ only:
16+ - master
17+cache:
18+ directories:
19+ - $HOME/.cabal/packages
20+ - $HOME/.cabal/store
21+before_cache:
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
630matrix:
731 include:
8− - env: CABALVER=1.18 GHCVER=7.8.4 HAPPYVER=1.19.4
9− addons: {apt: {packages: [cabal-install-1.18,ghc-7.8.4,happy-1.19.4], sources: [hvr-ghc]}}
10− - env: CABALVER=1.22 GHCVER=7.10.1 HAPPYVER=1.19.5
11− addons: {apt: {packages: [cabal-install-1.22,ghc-7.10.1,happy-1.19.5],sources: [hvr-ghc]}}
12− - env: CABALVER=head GHCVER=head HAPPYVER=head
13− addons: {apt: {packages: [cabal-install-head,ghc-head,happy-head], sources: [hvr-ghc]}}
14−
15− allow_failures:
16− - env: CABALVER=1.18 GHCVER=7.8.4 HAPPYVER=1.19.4
17− - env: CABALVER=head GHCVER=head HAPPYVER=head
18−
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"]}}
1942before_install:
20− - export PATH=/opt/ghc/$GHCVER/bin:/opt/cabal/$CABALVER/bin:$PATH:/opt/happy/$HAPPYVER/bin
21−
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
2274install:
23− - cabal --version
24− - echo "$(ghc --version) [$(ghc --print-project-git-commit-id 2> /dev/null || echo '?')]"
25− - travis_retry cabal update
26− - cabal install --only-dependencies --enable-tests --enable-benchmarks
27−
28−# Here starts the actual work to be performed for the package under test; 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
29126script:
30− - if [ -f configure.ac ]; then autoreconf -i; fi
31− - cabal configure --enable-tests --enable-benchmarks -v2 # -v2 provides useful information for debugging
32− - cabal build --ghc-options="-O0" # this builds all libraries and executables (including tests/benchmarks)
33− - cabal test
34− - cabal check
35− - cabal sdist # tests that a source-distribution can be generated
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
36160
37−# Check that the resulting source distribution can be built & installed.
38−# If there are no other `.tar.gz` files in `dist`, this can be even simpler:
39−# `cabal install --force-reinstalls dist/*-*.tar.gz`
40− - SRC_TGZ=$(cabal info . | awk '{print $2;exit}').tar.gz &&
41− (cd dist && cabal install --force-reinstalls "$SRC_TGZ")
161+# REGENDATA ("0.5.20191020",["--branches","master","--haddock-jobs=>=8.4","--output",".travis.yml","swagger2.cabal"])
162+# 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+5−1
@@ -1,7 +1,11 @@
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)
7+[![Stackage LTS](http://stackage.org/package/swagger2/badge/lts)](http://stackage.org/lts/package/swagger2)
8+[![Stackage Nightly](http://stackage.org/package/swagger2/badge/nightly)](http://stackage.org/nightly/package/swagger2)
59
610Swagger 2.0 data model.
711
@@ -9,7 +13,7 @@ The original Swagger 2.0 specification is available at http://swagger.io/specifi
913
1014## Usage
1115
12−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.
1317
1418Please refer to [haddock documentation](http://hackage.haskell.org/package/swagger2).
1519
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"
include/overlapping-compat.hnew file+8
@@ -0,0 +1,8 @@
1+#if __GLASGOW_HASKELL__ >= 710
2+#define OVERLAPPABLE_ {-# OVERLAPPABLE #-}
3+#define OVERLAPPING_ {-# OVERLAPPING #-}
4+#else
5+{-# LANGUAGE OverlappingInstances #-}
6+#define OVERLAPPABLE_
7+#define OVERLAPPING_
8+#endif
src/Data/Swagger.hs+140−21
@@ -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,34 +178,66 @@ 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 modify this structure. In combination with @'Monoid'@ instances, lenses
163−-- also make it fairly simple to construct/modify any part of the specification:
184+-- to work comfortably with it. In combination with @'Monoid'@ instances, lenses
185+-- make it fairly simple to construct/modify any part of the specification:
164186--
165187-- >>> :{
166−-- encode $ (mempty :: Swagger) & paths .~
167−-- [ ("/user", mempty & get ?~ (mempty
168−-- & produces ?~ MimeList ["application/json"]
169−-- & responses .~ (mempty
170−-- & responses . at 200 ?~ Inline (mempty & schema ?~ Ref (Reference "#/definitions/User")))))]
188+-- encode $ (mempty :: Swagger)
189+-- & definitions .~ [ ("User", mempty & type_ ?~ SwaggerString) ]
190+-- & paths .~
191+-- [ ("/user", mempty & get ?~ (mempty
192+-- & produces ?~ MimeList ["application/json"]
193+-- & at 200 ?~ ("OK" & _Inline.schema ?~ Ref (Reference "User"))
194+-- & at 404 ?~ "User info not found")) ]
171195-- :}
172−-- "{\"swagger\":\"2.0\",\"info\":{\"version\":\"\",\"title\":\"\"},\"paths\":{\"/user\":{\"get\":{\"responses\":{\"200\":{\"schema\":{\"$ref\":\"#/definitions/#/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\"}}}"
173197--
174−-- In the snippet above we declare API paths with a single path @/user@ providing method @GET@
175−-- which produces @application/json@ output and should respond with code @200@ and body specified
176−-- by schema @User@ (which should be defined in @definitions@ property of swagger specification).
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
200+-- 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.
177202--
178−-- Since @'ParamSchema'@ is basically the /base schema specification/, a special
179−-- @'HasParamSchema'@ class has been introduced to generalize @'ParamSchema'@ lenses
180−-- and allow them to be used by any type that has a @'ParamSchema'@:
203+-- For convenience, @swagger2@ uses /classy field lenses/. It means that
204+-- field accessor names can be overloaded for different types. One such
205+-- common field is @'description'@. Many components of a Swagger specification
206+-- can have descriptions, and you can use the same name for them:
181207--
208+-- >>> encode $ (mempty :: Response) & description .~ "No content"
209+-- "{\"description\":\"No content\"}"
182210-- >>> :{
183211-- encode $ (mempty :: Schema)
184−-- & title ?~ "Email"
185−-- & type_ .~ SwaggerString
186−-- & format ?~ "email"
212+-- & type_ ?~ SwaggerBoolean
213+-- & description ?~ "To be or not to be"
214+-- :}
215+-- "{\"description\":\"To be or not to be\",\"type\":\"boolean\"}"
216+--
217+-- @'ParamSchema'@ is basically the /base schema specification/ and many types contain it (see @'HasParamSchema'@).
218+-- So for convenience, all @'ParamSchema'@ fields are transitively made fields of the type that has it.
219+-- For example, you can use @'type_'@ to access @'SwaggerType'@ of @'Header'@ schema without having to use @'paramSchema'@:
220+--
221+-- >>> encode $ (mempty :: Header) & type_ ?~ SwaggerNumber
222+-- "{\"type\":\"number\"}"
223+--
224+-- Additionally, to simplify working with @'Response'@, both @'Operation'@ and @'Responses'@
225+-- have direct access to it via @'at' code@. Example:
226+--
227+-- >>> :{
228+-- encode $ (mempty :: Operation)
229+-- & at 404 ?~ "Not found"
187230-- :}
188−-- "{\"format\":\"email\",\"title\":\"Email\",\"type\":\"string\"}"
231+-- "{\"responses\":{\"404\":{\"description\":\"Not found\"}}}"
232+--
233+-- You might've noticed that @'type_'@ has an extra underscore in its name
234+-- compared to, say, @'description'@ field accessor.
235+-- This is because @type@ is a keyword in Haskell.
236+-- A few other field accessors are modified in this way:
237+--
238+-- - @'in_'@, @'type_'@, @'default_'@ (as keywords);
239+-- - @'maximum_'@, @'minimum_'@, @'head_'@ (as conflicting with @Prelude@);
240+-- - @'enum_'@ (as conflicting with @Control.Lens@).
189241
190242-- $schema
191243--
@@ -198,8 +250,8 @@ import Data.Swagger.Internal
198250-- with properties in addition to what @'ParamSchema'@ provides.
199251--
200252-- In most cases you will have a Haskell data type for which you would like to
201−-- define a corresponding schema. To facilitate thise use case
202−-- this library provides two classes for schema encoding.
253+-- define a corresponding schema. To facilitate this use case
254+-- @swagger2@ provides two classes for schema encoding.
203255-- Both these classes provide means to encode /types/ as Swagger /schemas/.
204256--
205257-- @'ToParamSchema'@ is intended to be used for primitive API endpoint parameters,
@@ -226,6 +278,73 @@ import Data.Swagger.Internal
226278-- >>> encode (Person "David" 28)
227279-- "{\"age\":28,\"name\":\"David\"}"
228280-- >>> encode $ toSchema (Proxy :: Proxy Person)
229−-- "{\"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
230336--
231337
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+91−10
@@ -2,12 +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
14+import Prelude ()
15+import Prelude.Compat
16+
717import Control.Monad
18+import Control.Monad.Cont (ContT)
19+import Control.Monad.List (ListT)
20+import Control.Monad.Reader (ReaderT)
821import 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
931import Data.Functor.Identity
10−import Data.Monoid
1132
1233-- | A declare monad transformer parametrized by:
1334--
@@ -24,22 +45,22 @@ import Data.Monoid
2445newtype DeclareT d m a = DeclareT { runDeclareT :: d -> m (d, a) }
2546 deriving (Functor)
2647
27−instance (Monad m, Monoid d) => Applicative (DeclareT d m) where
48+instance (Applicative m, Monad m, Monoid d) => Applicative (DeclareT d m) where
2849 pure x = DeclareT (\_ -> pure (mempty, x))
2950 DeclareT df <*> DeclareT dx = DeclareT $ \d -> do
3051 ~(d', f) <- df d
31− ~(d'', x) <- dx (d <> d')
32− return (d' <> d'', f x)
52+ ~(d'', x) <- dx (mappend d d')
53+ return (mappend d' d'', f x)
3354
34−instance (Monad m, Monoid d) => Monad (DeclareT d m) where
55+instance (Applicative m, Monad m, Monoid d) => Monad (DeclareT d m) where
3556 return x = DeclareT (\_ -> pure (mempty, x))
3657 DeclareT dx >>= f = DeclareT $ \d -> do
3758 ~(d', x) <- dx d
38− ~(d'', y) <- runDeclareT (f x) (d <> d')
39− return (d' <> d'', y)
59+ ~(d'', y) <- runDeclareT (f x) (mappend d d')
60+ return (mappend d' d'', y)
4061
4162instance Monoid d => MonadTrans (DeclareT d) where
42− lift m = DeclareT (\_ -> (,) mempty <$> m)
63+ lift m = DeclareT (\_ -> (,) mempty `liftM` m)
4364
4465-- |
4566-- Definitions of @declare@ and @look@ must satisfy the following laws:
@@ -58,16 +79,23 @@ instance Monoid d => MonadTrans (DeclareT d) where
5879-- [/@look@ as left identity/]
5980-- @'look' >> m == m@
6081-- for every @m@
61−class Monad m => MonadDeclare d m | m -> d where
82+class (Applicative m, Monad m) => MonadDeclare d m | m -> d where
6283 -- | @'declare' x@ is an action that produces the output @x@.
6384 declare :: d -> m ()
6485 -- | @'look'@ is an action that returns all the output so far.
6586 look :: m d
6687
67−instance (Monad m, Monoid d) => MonadDeclare d (DeclareT d m) where
88+instance (Applicative m, Monad m, Monoid d) => MonadDeclare d (DeclareT d m) where
6889 declare d = DeclareT (\_ -> return (d, ()))
6990 look = DeclareT (\d -> return (mempty, d))
7091
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+
7199-- | Retrieve a function of all the output so far.
72100looks :: MonadDeclare d m => (d -> a) -> m a
73101looks f = f <$> look
@@ -116,3 +144,56 @@ execDeclare m = runIdentity . execDeclareT m
116144undeclare :: Monoid d => Declare d a -> a
117145undeclare = runIdentity . undeclareT
118146
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+417−147
@@ -1,4 +1,7 @@
1+{-# LANGUAGE CPP #-}
2+{-# LANGUAGE DataKinds #-}
13{-# LANGUAGE DeriveDataTypeable #-}
4+{-# LANGUAGE DeriveFunctor #-}
25{-# LANGUAGE DeriveGeneric #-}
36{-# LANGUAGE DeriveTraversable #-}
47{-# LANGUAGE FlexibleContexts #-}
@@ -9,32 +12,66 @@
912{-# LANGUAGE RecordWildCards #-}
1013{-# LANGUAGE ScopedTypeVariables #-}
1114{-# LANGUAGE StandaloneDeriving #-}
15+{-# LANGUAGE TemplateHaskell #-}
16+{-# LANGUAGE TypeFamilies #-}
1217{-# LANGUAGE UndecidableInstances #-}
18+#if __GLASGOW_HASKELL__ <710
19+{-# LANGUAGE PolyKinds #-}
20+#endif
21+#include "overlapping-compat.h"
1322module Data.Swagger.Internal where
1423
24+import Prelude ()
25+import Prelude.Compat
26+
27+import Control.Lens ((&), (.~), (?~))
1528import Control.Applicative
16−import Control.Monad
1729import Data.Aeson
1830import qualified Data.Aeson.Types as JSON
1931import Data.Data (Data(..), Typeable, mkConstr, mkDataType, Fixity(..), Constr, DataType, constrIndex)
20−import Data.HashMap.Strict (HashMap)
32+import Data.Hashable (Hashable)
2133import qualified Data.HashMap.Strict as HashMap
34+import Data.HashSet.InsOrd (InsOrdHashSet)
2235import Data.Map (Map)
2336import qualified Data.Map as Map
24−import Data.Monoid
37+import Data.Monoid (Monoid (..))
38+import Data.Semigroup.Compat (Semigroup (..))
2539import Data.Scientific (Scientific)
26−import Data.String (fromString)
40+import Data.String (IsString(..))
2741import Data.Text (Text)
2842import qualified Data.Text as Text
2943import GHC.Generics (Generic)
30−import Network (HostName, PortNumber)
44+import Network.Socket (HostName, PortNumber)
3145import Network.HTTP.Media (MediaType)
3246import Text.Read (readMaybe)
3347
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)
3460import Data.Swagger.Internal.Utils
3561
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+
3673-- | A list of definitions that can be used in references.
37−type Definitions = HashMap Text
74+type Definitions = InsOrdHashMap Text
3875
3976-- | This is the root document object for the API specification.
4077data Swagger = Swagger
@@ -66,7 +103,7 @@ data Swagger = Swagger
66103 -- | The available paths and operations for the API.
67104 -- Holds the relative paths to the individual endpoints.
68105 -- The path is appended to the @'basePath'@ in order to construct the full URL.
69− , _swaggerPaths :: HashMap FilePath PathItem
106+ , _swaggerPaths :: InsOrdHashMap FilePath PathItem
70107
71108 -- | An object to hold data types produced and consumed by operations.
72109 , _swaggerDefinitions :: Definitions Schema
@@ -80,7 +117,7 @@ data Swagger = Swagger
80117 , _swaggerResponses :: Definitions Response
81118
82119 -- | Security scheme definitions that can be used across the specification.
83− , _swaggerSecurityDefinitions :: Definitions SecurityScheme
120+ , _swaggerSecurityDefinitions :: SecurityDefinitions
84121
85122 -- | A declaration of which security schemes are applied for the API as a whole.
86123 -- The list of values describes alternative security schemes that can be used
@@ -93,7 +130,7 @@ data Swagger = Swagger
93130 -- Not all tags that are used by the Operation Object must be declared.
94131 -- The tags that are not declared may be organized randomly or based on the tools' logic.
95132 -- Each tag name in the list MUST be unique.
96− , _swaggerTags :: [Tag]
133+ , _swaggerTags :: InsOrdHashSet Tag
97134
98135 -- | Additional external documentation.
99136 , _swaggerExternalDocs :: Maybe ExternalDocs
@@ -145,12 +182,18 @@ data License = License
145182 , _licenseUrl :: Maybe URL
146183 } deriving (Eq, Show, Generic, Data, Typeable)
147184
185+instance IsString License where
186+ fromString s = License (fromString s) Nothing
187+
148188-- | The host (name or ip) serving the API. It MAY include a port.
149189data Host = Host
150190 { _hostName :: HostName -- ^ Host name.
151191 , _hostPort :: Maybe PortNumber -- ^ Optional port.
152192 } deriving (Eq, Show, Generic, Typeable)
153193
194+instance IsString Host where
195+ fromString s = Host s Nothing
196+
154197hostConstr :: Constr
155198hostConstr = mkConstr hostDataType "Host" [] Prefix
156199
@@ -209,7 +252,7 @@ data PathItem = PathItem
209252data Operation = Operation
210253 { -- | A list of tags for API documentation control.
211254 -- Tags can be used for logical grouping of operations by resources or any other qualifier.
212− _operationTags :: [TagName]
255+ _operationTags :: InsOrdHashSet TagName
213256
214257 -- | A short summary of what the operation does.
215258 -- For maximum readability in the swagger-ui, this field SHOULD be less than 120 characters.
@@ -266,7 +309,7 @@ data Operation = Operation
266309 } deriving (Eq, Show, Generic, Data, Typeable)
267310
268311newtype MimeList = MimeList { getMimeList :: [MediaType] }
269− deriving (Eq, Show, Monoid, Typeable)
312+ deriving (Eq, Show, Semigroup, Monoid, Typeable)
270313
271314mimeListConstr :: Constr
272315mimeListConstr = mkConstr mimeListDataType "MimeList" ["getMimeList"] Prefix
@@ -317,8 +360,8 @@ data ParamOtherSchema = ParamOtherSchema
317360 -- Default value is @False@.
318361 , _paramOtherSchemaAllowEmptyValue :: Maybe Bool
319362
320− , _paramOtherSchemaParamSchema :: ParamSchema ParamOtherSchema
321− } deriving (Eq, Show, Generic, Data, Typeable)
363+ , _paramOtherSchemaParamSchema :: ParamSchema 'SwaggerKindParamOtherSchema
364+ } deriving (Eq, Show, Generic, Typeable, Data)
322365
323366-- | Items for @'SwaggerArray'@ schemas.
324367--
@@ -331,28 +374,78 @@ data ParamOtherSchema = ParamOtherSchema
331374--
332375-- @'SwaggerItemsArray'@ should be used to specify tuple @'Schema'@s.
333376data SwaggerItems t where
334− SwaggerItemsPrimitive :: Maybe (CollectionFormat t) -> ParamSchema t -> SwaggerItems t
335− SwaggerItemsObject :: Referenced Schema -> SwaggerItems Schema
336− 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
380+ deriving (Typeable)
337381
338382deriving instance Eq (SwaggerItems t)
339383deriving instance Show (SwaggerItems t)
340−deriving instance Typeable (SwaggerItems t)
384+--deriving instance Typeable (SwaggerItems t)
341385
342386swaggerItemsPrimitiveConstr :: Constr
343387swaggerItemsPrimitiveConstr = mkConstr swaggerItemsDataType "SwaggerItemsPrimitive" [] Prefix
344388
389+swaggerItemsObjectConstr :: Constr
390+swaggerItemsObjectConstr = mkConstr swaggerItemsDataType "SwaggerItemsObject" [] Prefix
391+
392+swaggerItemsArrayConstr :: Constr
393+swaggerItemsArrayConstr = mkConstr swaggerItemsDataType "SwaggerItemsArray" [] Prefix
394+
345395swaggerItemsDataType :: DataType
346396swaggerItemsDataType = mkDataType "Data.Swagger.SwaggerItems" [swaggerItemsPrimitiveConstr]
347397
348−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
349403 gunfold k z c = case constrIndex c of
350404 1 -> k (k (z SwaggerItemsPrimitive))
351405 _ -> error $ "Data.Data.gunfold: Constructor " ++ show c ++ " is not of type (SwaggerItems t)."
352406 toConstr _ = swaggerItemsPrimitiveConstr
353407 dataTypeOf _ = swaggerItemsDataType
354408
355−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
356449
357450data SwaggerType t where
358451 SwaggerString :: SwaggerType t
@@ -360,44 +453,44 @@ data SwaggerType t where
360453 SwaggerInteger :: SwaggerType t
361454 SwaggerBoolean :: SwaggerType t
362455 SwaggerArray :: SwaggerType t
363− SwaggerFile :: SwaggerType ParamOtherSchema
364− SwaggerNull :: SwaggerType Schema
365− SwaggerObject :: SwaggerType Schema
456+ SwaggerFile :: SwaggerType 'SwaggerKindParamOtherSchema
457+ SwaggerNull :: SwaggerType 'SwaggerKindSchema
458+ SwaggerObject :: SwaggerType 'SwaggerKindSchema
459+ deriving (Typeable)
366460
367461deriving instance Eq (SwaggerType t)
368462deriving instance Show (SwaggerType t)
369−deriving instance Typeable (SwaggerType t)
370463
371464swaggerTypeConstr :: Data (SwaggerType t) => SwaggerType t -> Constr
372465swaggerTypeConstr t = mkConstr (dataTypeOf t) (show t) [] Prefix
373466
374−swaggerTypeDataType :: Data (SwaggerType t) => SwaggerType t -> DataType
467+swaggerTypeDataType :: {- Data (SwaggerType t) => -} SwaggerType t -> DataType
375468swaggerTypeDataType _ = mkDataType "Data.Swagger.SwaggerType" swaggerTypeConstrs
376469
377−swaggerCommonTypes :: [SwaggerType t]
470+swaggerCommonTypes :: [SwaggerType k]
378471swaggerCommonTypes = [SwaggerString, SwaggerNumber, SwaggerInteger, SwaggerBoolean, SwaggerArray]
379472
380−swaggerParamTypes :: [SwaggerType ParamOtherSchema]
473+swaggerParamTypes :: [SwaggerType 'SwaggerKindParamOtherSchema]
381474swaggerParamTypes = swaggerCommonTypes ++ [SwaggerFile]
382475
383−swaggerSchemaTypes :: [SwaggerType Schema]
476+swaggerSchemaTypes :: [SwaggerType 'SwaggerKindSchema]
384477swaggerSchemaTypes = swaggerCommonTypes ++ [error "SwaggerFile is invalid SwaggerType Schema", SwaggerNull, SwaggerObject]
385478
386479swaggerTypeConstrs :: [Constr]
387−swaggerTypeConstrs = map swaggerTypeConstr (swaggerCommonTypes :: [SwaggerType Schema])
480+swaggerTypeConstrs = map swaggerTypeConstr (swaggerCommonTypes :: [SwaggerType 'SwaggerKindSchema])
388481 ++ [swaggerTypeConstr SwaggerFile, swaggerTypeConstr SwaggerNull, swaggerTypeConstr SwaggerObject]
389482
390−instance {-# OVERLAPPABLE #-} Typeable t => Data (SwaggerType t) where
483+instance Typeable t => Data (SwaggerType ('SwaggerKindNormal t)) where
391484 gunfold = gunfoldEnum "SwaggerType" swaggerCommonTypes
392485 toConstr = swaggerTypeConstr
393486 dataTypeOf = swaggerTypeDataType
394487
395−instance {-# OVERLAPPING #-} Data (SwaggerType ParamOtherSchema) where
488+instance Data (SwaggerType 'SwaggerKindParamOtherSchema) where
396489 gunfold = gunfoldEnum "SwaggerType ParamOtherSchema" swaggerParamTypes
397490 toConstr = swaggerTypeConstr
398491 dataTypeOf = swaggerTypeDataType
399492
400−instance {-# OVERLAPPING #-} Data (SwaggerType Schema) where
493+instance Data (SwaggerType 'SwaggerKindSchema) where
401494 gunfold = gunfoldEnum "SwaggerType Schema" swaggerSchemaTypes
402495 toConstr = swaggerTypeConstr
403496 dataTypeOf = swaggerTypeDataType
@@ -437,11 +530,11 @@ data CollectionFormat t where
437530 -- Corresponds to multiple parameter instances
438531 -- instead of multiple values for a single instance @foo=bar&foo=baz@.
439532 -- This is valid only for parameters in @'ParamQuery'@ or @'ParamFormData'@.
440− CollectionMulti :: CollectionFormat ParamOtherSchema
533+ CollectionMulti :: CollectionFormat 'SwaggerKindParamOtherSchema
534+ deriving (Typeable)
441535
442536deriving instance Eq (CollectionFormat t)
443537deriving instance Show (CollectionFormat t)
444−deriving instance Typeable (CollectionFormat t)
445538
446539collectionFormatConstr :: CollectionFormat t -> Constr
447540collectionFormatConstr cf = mkConstr collectionFormatDataType (show cf) [] Prefix
@@ -453,12 +546,12 @@ collectionFormatDataType = mkDataType "Data.Swagger.CollectionFormat" $
453546collectionCommonFormats :: [CollectionFormat t]
454547collectionCommonFormats = [ CollectionCSV, CollectionSSV, CollectionTSV, CollectionPipes ]
455548
456−instance {-# OVERLAPPABLE #-} Data t => Data (CollectionFormat t) where
549+instance Data t => Data (CollectionFormat ('SwaggerKindNormal t)) where
457550 gunfold = gunfoldEnum "CollectionFormat" collectionCommonFormats
458551 toConstr = collectionFormatConstr
459552 dataTypeOf _ = collectionFormatDataType
460553
461−deriving instance {-# OVERLAPPING #-} Data (CollectionFormat ParamOtherSchema)
554+deriving instance Data (CollectionFormat 'SwaggerKindParamOtherSchema)
462555
463556type ParamName = Text
464557
@@ -467,9 +560,9 @@ data Schema = Schema
467560 , _schemaDescription :: Maybe Text
468561 , _schemaRequired :: [ParamName]
469562
470− , _schemaAllOf :: Maybe [Schema]
471− , _schemaProperties :: HashMap Text (Referenced Schema)
472− , _schemaAdditionalProperties :: Maybe Schema
563+ , _schemaAllOf :: Maybe [Referenced Schema]
564+ , _schemaProperties :: InsOrdHashMap Text (Referenced Schema)
565+ , _schemaAdditionalProperties :: Maybe AdditionalProperties
473566
474567 , _schemaDiscriminator :: Maybe Text
475568 , _schemaReadOnly :: Maybe Bool
@@ -480,7 +573,7 @@ data Schema = Schema
480573 , _schemaMaxProperties :: Maybe Integer
481574 , _schemaMinProperties :: Maybe Integer
482575
483− , _schemaParamSchema :: ParamSchema Schema
576+ , _schemaParamSchema :: ParamSchema 'SwaggerKindSchema
484577 } deriving (Eq, Show, Generic, Data, Typeable)
485578
486579-- | A @'Schema'@ with an optional name.
@@ -490,7 +583,10 @@ data NamedSchema = NamedSchema
490583 , _namedSchemaSchema :: Schema
491584 } deriving (Eq, Show, Generic, Data, Typeable)
492585
493−data ParamSchema t = ParamSchema
586+-- | Regex pattern for @string@ type.
587+type Pattern = Text
588+
589+data ParamSchema (t :: SwaggerKind *) = ParamSchema
494590 { -- | Declares the value of the parameter that the server will use if none is provided,
495591 -- for example a @"count"@ to control the number of results per page might default to @100@
496592 -- if not supplied by the client in the request.
@@ -498,7 +594,7 @@ data ParamSchema t = ParamSchema
498594 -- Unlike JSON Schema this value MUST conform to the defined type for this parameter.
499595 _paramSchemaDefault :: Maybe Value
500596
501− , _paramSchemaType :: SwaggerType t
597+ , _paramSchemaType :: Maybe (SwaggerType t)
502598 , _paramSchemaFormat :: Maybe Format
503599 , _paramSchemaItems :: Maybe (SwaggerItems t)
504600 , _paramSchemaMaximum :: Maybe Scientific
@@ -507,7 +603,7 @@ data ParamSchema t = ParamSchema
507603 , _paramSchemaExclusiveMinimum :: Maybe Bool
508604 , _paramSchemaMaxLength :: Maybe Integer
509605 , _paramSchemaMinLength :: Maybe Integer
510− , _paramSchemaPattern :: Maybe Text
606+ , _paramSchemaPattern :: Maybe Pattern
511607 , _paramSchemaMaxItems :: Maybe Integer
512608 , _paramSchemaMinItems :: Maybe Integer
513609 , _paramSchemaUniqueItems :: Maybe Bool
@@ -515,7 +611,7 @@ data ParamSchema t = ParamSchema
515611 , _paramSchemaMultipleOf :: Maybe Scientific
516612 } deriving (Eq, Show, Generic, Typeable)
517613
518−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)
519615
520616data Xml = Xml
521617 { -- | Replaces the name of the element/attribute used for the described schema property.
@@ -557,7 +653,7 @@ data Responses = Responses
557653
558654 -- | Any HTTP status code can be used as the property name (one property per HTTP status code).
559655 -- Describes the expected response for those HTTP status codes.
560− , _responsesResponses :: HashMap HttpStatusCode (Referenced Response)
656+ , _responsesResponses :: InsOrdHashMap HttpStatusCode (Referenced Response)
561657 } deriving (Eq, Show, Generic, Data, Typeable)
562658
563659type HttpStatusCode = Int
@@ -576,19 +672,22 @@ data Response = Response
576672 , _responseSchema :: Maybe (Referenced Schema)
577673
578674 -- | A list of headers that are sent with the response.
579− , _responseHeaders :: HashMap HeaderName Header
675+ , _responseHeaders :: InsOrdHashMap HeaderName Header
580676
581677 -- | An example of the response message.
582678 , _responseExamples :: Maybe Example
583679 } deriving (Eq, Show, Generic, Data, Typeable)
584680
681+instance IsString Response where
682+ fromString s = Response (fromString s) Nothing mempty Nothing
683+
585684type HeaderName = Text
586685
587686data Header = Header
588687 { -- | A short description of the header.
589688 _headerDescription :: Maybe Text
590689
591− , _headerParamSchema :: ParamSchema Header
690+ , _headerParamSchema :: ParamSchema ('SwaggerKindNormal Header)
592691 } deriving (Eq, Show, Generic, Data, Typeable)
593692
594693data Example = Example { getExample :: Map MediaType Value }
@@ -639,7 +738,7 @@ data OAuth2Params = OAuth2Params
639738 _oauth2Flow :: OAuth2Flow
640739
641740 -- | The available scopes for the OAuth2 security scheme.
642− , _oauth2Scopes :: HashMap Text Text
741+ , _oauth2Scopes :: InsOrdHashMap Text Text
643742 } deriving (Eq, Show, Generic, Data, Typeable)
644743
645744data SecuritySchemeType
@@ -656,12 +755,28 @@ data SecurityScheme = SecurityScheme
656755 , _securitySchemeDescription :: Maybe Text
657756 } deriving (Eq, Show, Generic, Data, Typeable)
658757
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+
659774-- | Lists the required security schemes to execute this operation.
660775-- The object can have multiple security schemes declared in it which are all required
661776-- (that is, there is a logical AND between the schemes).
662777newtype SecurityRequirement = SecurityRequirement
663− { getSecurityRequirement :: HashMap Text [Text]
664− } 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)
665780
666781-- | Tag name.
667782type TagName = Text
@@ -678,7 +793,12 @@ data Tag = Tag
678793
679794 -- | Additional external documentation for this tag.
680795 , _tagExternalDocs :: Maybe ExternalDocs
681− } 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
682802
683803-- | Allows referencing an external resource for extended documentation.
684804data ExternalDocs = ExternalDocs
@@ -688,7 +808,9 @@ data ExternalDocs = ExternalDocs
688808
689809 -- | The URL for the target documentation.
690810 , _externalDocsUrl :: URL
691− } deriving (Eq, Show, Generic, Data, Typeable)
811+ } deriving (Eq, Ord, Show, Generic, Data, Typeable)
812+
813+instance Hashable ExternalDocs
692814
693815-- | A simple object to allow referencing other definitions in the specification.
694816-- It can be used to reference parameters and responses that are defined at the top level for reuse.
@@ -698,65 +820,116 @@ newtype Reference = Reference { getReference :: Text }
698820data Referenced a
699821 = Ref Reference
700822 | Inline a
701− 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)
702829
703−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)
704834
705835-- =======================================================================
706836-- Monoid instances
707837-- =======================================================================
708838
839+instance Semigroup Swagger where
840+ (<>) = genericMappend
709841instance Monoid Swagger where
710842 mempty = genericMempty
711− mappend = genericMappend
843+ mappend = (<>)
712844
845+instance Semigroup Info where
846+ (<>) = genericMappend
713847instance Monoid Info where
714848 mempty = genericMempty
715− mappend = genericMappend
849+ mappend = (<>)
850+
851+instance Semigroup Contact where
852+ (<>) = genericMappend
853+instance Monoid Contact where
854+ mempty = genericMempty
855+ mappend = (<>)
716856
857+instance Semigroup PathItem where
858+ (<>) = genericMappend
717859instance Monoid PathItem where
718860 mempty = genericMempty
719− mappend = genericMappend
861+ mappend = (<>)
720862
863+instance Semigroup Schema where
864+ (<>) = genericMappend
721865instance Monoid Schema where
722866 mempty = genericMempty
723− mappend = genericMappend
867+ mappend = (<>)
724868
869+instance Semigroup (ParamSchema t) where
870+ (<>) = genericMappend
725871instance Monoid (ParamSchema t) where
726872 mempty = genericMempty
727− mappend = genericMappend
873+ mappend = (<>)
728874
875+instance Semigroup Param where
876+ (<>) = genericMappend
729877instance Monoid Param where
730878 mempty = genericMempty
731− mappend = genericMappend
879+ mappend = (<>)
732880
881+instance Semigroup ParamOtherSchema where
882+ (<>) = genericMappend
733883instance Monoid ParamOtherSchema where
734884 mempty = genericMempty
735− mappend = genericMappend
885+ mappend = (<>)
736886
887+instance Semigroup Header where
888+ (<>) = genericMappend
737889instance Monoid Header where
738890 mempty = genericMempty
739− mappend = genericMappend
891+ mappend = (<>)
740892
893+instance Semigroup Responses where
894+ (<>) = genericMappend
741895instance Monoid Responses where
742896 mempty = genericMempty
743− mappend = genericMappend
897+ mappend = (<>)
744898
899+instance Semigroup Response where
900+ (<>) = genericMappend
745901instance Monoid Response where
746902 mempty = genericMempty
747− mappend = genericMappend
903+ mappend = (<>)
748904
905+instance Semigroup ExternalDocs where
906+ (<>) = genericMappend
749907instance Monoid ExternalDocs where
750908 mempty = genericMempty
751− mappend = genericMappend
909+ mappend = (<>)
752910
911+instance Semigroup Operation where
912+ (<>) = genericMappend
753913instance Monoid Operation where
754914 mempty = genericMempty
755− mappend = genericMappend
915+ mappend = (<>)
756916
917+instance Semigroup Example where
918+ (<>) = genericMappend
757919instance Monoid Example where
758920 mempty = genericMempty
759− 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 = (<>)
760933
761934-- =======================================================================
762935-- SwaggerMonoid helper instances
@@ -772,6 +945,8 @@ instance SwaggerMonoid Responses
772945instance SwaggerMonoid Response
773946instance SwaggerMonoid ExternalDocs
774947instance SwaggerMonoid Operation
948+instance SwaggerMonoid SecurityDefinitions
949+instance (Eq a, Hashable a) => SwaggerMonoid (InsOrdHashSet a)
775950
776951instance SwaggerMonoid MimeList
777952deriving instance SwaggerMonoid URL
@@ -784,13 +959,13 @@ instance SwaggerMonoid ParamLocation where
784959 swaggerMempty = ParamQuery
785960 swaggerMappend _ y = y
786961
787−instance SwaggerMonoid (HashMap FilePath PathItem) where
788− swaggerMempty = HashMap.empty
789− swaggerMappend = HashMap.unionWith mappend
962+instance OVERLAPPING_ SwaggerMonoid (InsOrdHashMap FilePath PathItem) where
963+ swaggerMempty = InsOrdHashMap.empty
964+ swaggerMappend = InsOrdHashMap.unionWith mappend
790965
791966instance Monoid a => SwaggerMonoid (Referenced a) where
792967 swaggerMempty = Inline mempty
793− swaggerMappend (Inline x) (Inline y) = Inline (x <> y)
968+ swaggerMappend (Inline x) (Inline y) = Inline (mappend x y)
794969 swaggerMappend _ y = y
795970
796971instance SwaggerMonoid ParamAnySchema where
@@ -884,7 +1059,8 @@ instance ToJSON OAuth2Flow where
8841059 , "tokenUrl" .= tokenUrl ]
8851060
8861061instance ToJSON OAuth2Params where
887− toJSON = omitEmpties . genericToJSONWithSub "flow" (jsonPrefix "oauth2")
1062+ toJSON = sopSwaggerGenericToJSON
1063+ DEFINE_TOENCODING
8881064
8891065instance ToJSON SecuritySchemeType where
8901066 toJSON SecuritySchemeBasic
@@ -897,28 +1073,37 @@ instance ToJSON SecuritySchemeType where
8971073 <+> object [ "type" .= ("oauth2" :: Text) ]
8981074
8991075instance ToJSON Swagger where
900− toJSON = omitEmpties . addVersion . genericToJSON (jsonPrefix "swagger")
901− where
902− addVersion (Object o) = Object (HashMap.insert "swagger" "2.0" o)
903− addVersion _ = error "impossible"
1076+ toJSON = sopSwaggerGenericToJSON
1077+ DEFINE_TOENCODING
9041078
9051079instance ToJSON SecurityScheme where
906− toJSON = genericToJSONWithSub "type" (jsonPrefix "securityScheme")
1080+ toJSON = sopSwaggerGenericToJSON
1081+ DEFINE_TOENCODING
9071082
9081083instance ToJSON Schema where
909− toJSON = omitEmptiesExcept f . genericToJSONWithSub "paramSchema" (jsonPrefix "schema")
910− where
911− f "items" (Array _) = True
912− f _ _ = False
1084+ toJSON = sopSwaggerGenericToJSON
1085+ DEFINE_TOENCODING
9131086
9141087instance ToJSON Header where
915− toJSON = genericToJSONWithSub "paramSchema" (jsonPrefix "header")
1088+ toJSON = sopSwaggerGenericToJSON
1089+ DEFINE_TOENCODING
9161090
917−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
9181098 toJSON (SwaggerItemsPrimitive fmt schema) = object
9191099 [ "collectionFormat" .= fmt
9201100 , "items" .= schema ]
9211101 toJSON (SwaggerItemsObject x) = object [ "items" .= x ]
1102+ toJSON (SwaggerItemsArray []) = object
1103+ [ "items" .= object []
1104+ , "maxItems" .= (0 :: Int)
1105+ , "example" .= Array mempty
1106+ ]
9221107 toJSON (SwaggerItemsArray x) = object [ "items" .= x ]
9231108
9241109instance ToJSON Host where
@@ -931,31 +1116,39 @@ instance ToJSON MimeList where
9311116 toJSON (MimeList xs) = toJSON (map show xs)
9321117
9331118instance ToJSON Param where
934− toJSON = genericToJSONWithSub "schema" (jsonPrefix "param")
1119+ toJSON = sopSwaggerGenericToJSON
1120+ DEFINE_TOENCODING
9351121
9361122instance ToJSON ParamAnySchema where
9371123 toJSON (ParamBody s) = object [ "in" .= ("body" :: Text), "schema" .= s ]
9381124 toJSON (ParamOther s) = toJSON s
9391125
9401126instance ToJSON ParamOtherSchema where
941− toJSON = genericToJSONWithSub "paramSchema" (jsonPrefix "paramOtherSchema")
1127+ toJSON = sopSwaggerGenericToJSON
1128+ DEFINE_TOENCODING
9421129
9431130instance ToJSON Responses where
944− toJSON (Responses def rs) = omitEmpties $
945− toJSON (hashMapMapKeys show rs) <+> object [ "default" .= def ]
1131+ toJSON = sopSwaggerGenericToJSON
1132+ DEFINE_TOENCODING
9461133
9471134instance ToJSON Response where
948− toJSON = omitEmpties . genericToJSON (jsonPrefix "response")
1135+ toJSON = sopSwaggerGenericToJSON
1136+ DEFINE_TOENCODING
9491137
9501138instance ToJSON Operation where
951− toJSON = omitEmpties . genericToJSON (jsonPrefix "operation")
1139+ toJSON = sopSwaggerGenericToJSON
1140+ DEFINE_TOENCODING
9521141
9531142instance ToJSON PathItem where
954− toJSON = omitEmpties . genericToJSON (jsonPrefix "pathItem")
1143+ toJSON = sopSwaggerGenericToJSON
1144+ DEFINE_TOENCODING
9551145
9561146instance ToJSON Example where
9571147 toJSON = toJSON . Map.mapKeys show . getExample
9581148
1149+instance ToJSON SecurityDefinitions where
1150+ toJSON (SecurityDefinitions sd) = toJSON sd
1151+
9591152instance ToJSON Reference where
9601153 toJSON (Reference ref) = object [ "$ref" .= ref ]
9611154
@@ -984,11 +1177,14 @@ instance ToJSON (CollectionFormat t) where
9841177 toJSON CollectionPipes = "pipes"
9851178 toJSON CollectionMulti = "multi"
9861179
987−instance ToJSON (ParamSchema t) where
988− toJSON = omitEmptiesExcept f . genericToJSONWithSub "items" (jsonPrefix "paramSchema")
989− where
990− f "items" (Array _) = True
991− 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
9921188
9931189-- =======================================================================
9941190-- Manual FromJSON instances
@@ -1008,7 +1204,7 @@ instance FromJSON OAuth2Flow where
10081204 parseJSON _ = empty
10091205
10101206instance FromJSON OAuth2Params where
1011− parseJSON = genericParseJSONWithSub "flow" (jsonPrefix "oauth2")
1207+ parseJSON = sopSwaggerGenericParseJSON
10121208
10131209instance FromJSON SecuritySchemeType where
10141210 parseJSON js@(Object o) = do
@@ -1021,57 +1217,65 @@ instance FromJSON SecuritySchemeType where
10211217 parseJSON _ = empty
10221218
10231219instance FromJSON Swagger where
1024− parseJSON js@(Object o) = do
1025− (version :: Text) <- o .: "swagger"
1026− when (version /= "2.0") empty
1027− (genericParseJSON (jsonPrefix "swagger")
1028− `withDefaults` [ "consumes" .= (mempty :: MimeList)
1029− , "produces" .= (mempty :: MimeList)
1030− , "security" .= ([] :: [SecurityRequirement])
1031− , "tags" .= ([] :: [Tag])
1032− , "definitions" .= (mempty :: Definitions Schema)
1033− , "parameters" .= (mempty :: Definitions Param)
1034− , "responses" .= (mempty :: Definitions Response)
1035− , "securityDefinitions" .= (mempty :: Definitions SecurityScheme)
1036− ] ) js
1037− parseJSON _ = empty
1220+ parseJSON = sopSwaggerGenericParseJSON
10381221
10391222instance FromJSON SecurityScheme where
1040− parseJSON = genericParseJSONWithSub "type" (jsonPrefix "securityScheme")
1223+ parseJSON = sopSwaggerGenericParseJSON
10411224
10421225instance FromJSON Schema where
1043− parseJSON = genericParseJSONWithSub "paramSchema" (jsonPrefix "schema")
1044− `withDefaults` [ "properties" .= (mempty :: HashMap Text Schema)
1045− , "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
10461233
10471234instance FromJSON Header where
1048− parseJSON = genericParseJSONWithSub "paramSchema" (jsonPrefix "header")
1235+ parseJSON = sopSwaggerGenericParseJSON
10491236
1050−instance {-# OVERLAPPABLE #-} (FromJSON (CollectionFormat t), FromJSON (ParamSchema t)) => FromJSON (SwaggerItems t) where
1051− parseJSON (Object o) = SwaggerItemsPrimitive
1237+instance (FromJSON (CollectionFormat ('SwaggerKindNormal t)), FromJSON (ParamSchema ('SwaggerKindNormal t))) => FromJSON (SwaggerItems ('SwaggerKindNormal t)) where
1238+ parseJSON = withObject "SwaggerItemsPrimitive" $ \o -> SwaggerItemsPrimitive
10521239 <$> o .:? "collectionFormat"
10531240 <*> (o .: "items" >>= parseJSON)
10541241
1055−instance {-# OVERLAPPING #-} FromJSON (SwaggerItems Schema) where
1056− 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
10571262 parseJSON js@(Array _) = SwaggerItemsArray <$> parseJSON js
10581263 parseJSON _ = empty
10591264
10601265instance FromJSON Host where
1061− parseJSON (String s) =
1062− case fromInteger <$> readMaybe portStr of
1063− Nothing | not (null portStr) -> fail $ "Invalid port `" ++ portStr ++ "'"
1064− mport -> pure $ Host host mport
1065− where
1066− (hostText, portText) = Text.breakOn ":" s
1067− [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 ++ "'"
10681272 parseJSON _ = empty
10691273
10701274instance FromJSON MimeList where
10711275 parseJSON js = (MimeList . map fromString) <$> parseJSON js
10721276
10731277instance FromJSON Param where
1074− parseJSON = genericParseJSONWithSub "schema" (jsonPrefix "param")
1278+ parseJSON = sopSwaggerGenericParseJSON
10751279
10761280instance FromJSON ParamAnySchema where
10771281 parseJSON js@(Object o) = do
@@ -1084,12 +1288,12 @@ instance FromJSON ParamAnySchema where
10841288 parseJSON _ = empty
10851289
10861290instance FromJSON ParamOtherSchema where
1087− parseJSON = genericParseJSONWithSub "paramSchema" (jsonPrefix "paramOtherSchema")
1291+ parseJSON = sopSwaggerGenericParseJSON
10881292
10891293instance FromJSON Responses where
10901294 parseJSON (Object o) = Responses
10911295 <$> o .:? "default"
1092− <*> (parseJSON (Object (HashMap.delete "default" o)) >>= hashMapReadKeys)
1296+ <*> (parseJSON (Object (HashMap.delete "default" o)))
10931297 parseJSON _ = empty
10941298
10951299instance FromJSON Example where
@@ -1098,16 +1302,16 @@ instance FromJSON Example where
10981302 pure $ Example (Map.mapKeys fromString m)
10991303
11001304instance FromJSON Response where
1101− parseJSON = genericParseJSON (jsonPrefix "response")
1102− `withDefaults` [ "headers" .= (mempty :: HashMap HeaderName Header) ]
1305+ parseJSON = sopSwaggerGenericParseJSON
11031306
11041307instance FromJSON Operation where
1105− parseJSON = genericParseJSON (jsonPrefix "operation")
1106− `withDefaults` [ "security" .= ([] :: [SecurityRequirement]) ]
1308+ parseJSON = sopSwaggerGenericParseJSON
11071309
11081310instance FromJSON PathItem where
1109− parseJSON = genericParseJSON (jsonPrefix "pathItem")
1110− `withDefaults` [ "parameters" .= ([] :: [Param]) ]
1311+ parseJSON = sopSwaggerGenericParseJSON
1312+
1313+instance FromJSON SecurityDefinitions where
1314+ parseJSON js = SecurityDefinitions <$> parseJSON js
11111315
11121316instance FromJSON Reference where
11131317 parseJSON (Object o) = Reference <$> o .: "$ref"
@@ -1124,6 +1328,7 @@ referencedParseJSON prefix js@(Object o) = do
11241328 case Text.stripPrefix prefix s of
11251329 Nothing -> fail $ "expected $ref of the form \"" <> Text.unpack prefix <> "*\", but got " <> show s
11261330 Just suffix -> pure (Reference suffix)
1331+referencedParseJSON _ _ = fail "referenceParseJSON: not an object"
11271332
11281333instance FromJSON (Referenced Schema) where parseJSON = referencedParseJSON "#/definitions/"
11291334instance FromJSON (Referenced Param) where parseJSON = referencedParseJSON "#/parameters/"
@@ -1132,26 +1337,91 @@ instance FromJSON (Referenced Response) where parseJSON = referencedParseJSON "#
11321337instance FromJSON Xml where
11331338 parseJSON = genericParseJSON (jsonPrefix "xml")
11341339
1135−instance FromJSON (SwaggerType Schema) where
1340+instance FromJSON (SwaggerType 'SwaggerKindSchema) where
11361341 parseJSON = parseOneOf [SwaggerString, SwaggerInteger, SwaggerNumber, SwaggerBoolean, SwaggerArray, SwaggerNull, SwaggerObject]
11371342
1138−instance FromJSON (SwaggerType ParamOtherSchema) where
1343+instance FromJSON (SwaggerType 'SwaggerKindParamOtherSchema) where
11391344 parseJSON = parseOneOf [SwaggerString, SwaggerInteger, SwaggerNumber, SwaggerBoolean, SwaggerArray, SwaggerFile]
11401345
1141−instance {-# OVERLAPPABLE #-} FromJSON (SwaggerType t) where
1346+instance FromJSON (SwaggerType ('SwaggerKindNormal t)) where
11421347 parseJSON = parseOneOf [SwaggerString, SwaggerInteger, SwaggerNumber, SwaggerBoolean, SwaggerArray]
11431348
1144−instance {-# OVERLAPPABLE #-} FromJSON (CollectionFormat t) where
1349+instance FromJSON (CollectionFormat ('SwaggerKindNormal t)) where
11451350 parseJSON = parseOneOf [CollectionCSV, CollectionSSV, CollectionTSV, CollectionPipes]
11461351
1147−instance FromJSON (CollectionFormat ParamOtherSchema) where
1148− 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]
11491355
1150−-- NOTE: The constraints @FromJSON (SwaggerType t)@ and
1151−-- @FromJSON (SwaggerItems t)@ are necessary here!
1152−-- Without the constraint the general instance will be used
1153−-- that only accepts common types (i.e. NOT object, null or file)
1154−-- and primitive array items.
1155−instance (FromJSON (SwaggerType t), FromJSON (SwaggerItems t)) => FromJSON (ParamSchema t) where
1156− parseJSON = genericParseJSONWithSub "items" (jsonPrefix "ParamSchema")
1356+instance FromJSON (CollectionFormat 'SwaggerKindParamOtherSchema) where
1357+ parseJSON = parseOneOf [CollectionCSV, CollectionSSV, CollectionTSV, CollectionPipes, CollectionMulti]
11571358
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+123−24
@@ -1,3 +1,5 @@
1+{-# LANGUAGE CPP #-}
2+{-# LANGUAGE DataKinds #-}
13{-# LANGUAGE DefaultSignatures #-}
24{-# LANGUAGE FlexibleContexts #-}
35{-# LANGUAGE FlexibleInstances #-}
@@ -6,12 +8,21 @@
68{-# LANGUAGE PackageImports #-}
79{-# LANGUAGE PolyKinds #-}
810{-# LANGUAGE ScopedTypeVariables #-}
11+{-# LANGUAGE TypeFamilies #-}
912{-# LANGUAGE TypeOperators #-}
1013{-# 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
21+#include "overlapping-compat.h"
1122module Data.Swagger.Internal.ParamSchema where
1223
1324import Control.Lens
14−import Data.Aeson
25+import Data.Aeson (ToJSON (..))
1526import Data.Proxy
1627import GHC.Generics
1728
@@ -20,15 +31,50 @@ import "unordered-containers" Data.HashSet (HashSet)
2031import Data.Monoid
2132import Data.Set (Set)
2233import Data.Scientific
34+import Data.Fixed (HasResolution(..), Fixed, Pico)
2335import qualified Data.Text as T
2436import qualified Data.Text.Lazy as TL
2537import 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)
2644import Data.Word
45+import Data.UUID.Types (UUID)
46+import Web.Cookie (SetCookie)
2747
2848import Data.Swagger.Internal
2949import Data.Swagger.Lens
3050import Data.Swagger.SchemaOptions
3151
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+
3278-- | Convert a type into a plain @'ParamSchema'@.
3379--
3480-- An example type and instance:
@@ -41,9 +87,9 @@ import Data.Swagger.SchemaOptions
4187-- data Direction = Up | Down
4288--
4389-- instance ToParamSchema Direction where
44−-- toParamSchema = mempty
45−-- & type_ .~ SwaggerString
46−-- & enum_ .~ [ \"Up\", \"Down\" ]
90+-- toParamSchema _ = mempty
91+-- & type_ ?~ SwaggerString
92+-- & enum_ ?~ [ \"Up\", \"Down\" ]
4793-- @
4894--
4995-- Instead of manually writing your @'ToParamSchema'@ instance you can
@@ -69,18 +115,24 @@ class ToParamSchema a where
69115 --
70116 -- >>> encode $ toParamSchema (Proxy :: Proxy Integer)
71117 -- "{\"type\":\"integer\"}"
72− toParamSchema :: proxy a -> ParamSchema t
73− 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
74120 toParamSchema = genericToParamSchema defaultSchemaOptions
75121
76−instance {-# OVERLAPPING #-} ToParamSchema String where
77− toParamSchema _ = mempty & type_ .~ SwaggerString
122+instance OVERLAPPING_ ToParamSchema String where
123+ toParamSchema _ = mempty & type_ ?~ SwaggerString
78124
79125instance ToParamSchema Bool where
80− toParamSchema _ = mempty & type_ .~ SwaggerBoolean
126+ toParamSchema _ = mempty & type_ ?~ SwaggerBoolean
81127
82128instance ToParamSchema Integer where
83− 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
84136
85137instance ToParamSchema Int where toParamSchema = toParamSchemaBoundedIntegral
86138instance ToParamSchema Int8 where toParamSchema = toParamSchemaBoundedIntegral
@@ -102,40 +154,51 @@ instance ToParamSchema Word64 where toParamSchema = toParamSchemaBoundedIntegral
102154--
103155-- >>> encode $ toParamSchemaBoundedIntegral (Proxy :: Proxy Int8)
104156-- "{\"maximum\":127,\"minimum\":-128,\"type\":\"integer\"}"
105−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
106158toParamSchemaBoundedIntegral _ = mempty
107− & type_ .~ SwaggerInteger
159+ & type_ ?~ SwaggerInteger
108160 & minimum_ ?~ fromInteger (toInteger (minBound :: a))
109161 & maximum_ ?~ fromInteger (toInteger (maxBound :: a))
110162
111163instance ToParamSchema Char where
112164 toParamSchema _ = mempty
113− & type_ .~ SwaggerString
165+ & type_ ?~ SwaggerString
114166 & maxLength ?~ 1
115167 & minLength ?~ 1
116168
117169instance ToParamSchema Scientific where
118− 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))
119176
120177instance ToParamSchema Double where
121178 toParamSchema _ = mempty
122− & type_ .~ SwaggerNumber
179+ & type_ ?~ SwaggerNumber
123180 & format ?~ "double"
124181
125182instance ToParamSchema Float where
126183 toParamSchema _ = mempty
127− & type_ .~ SwaggerNumber
184+ & type_ ?~ SwaggerNumber
128185 & format ?~ "float"
129186
130187timeParamSchema :: String -> ParamSchema t
131188timeParamSchema fmt = mempty
132− & type_ .~ SwaggerString
189+ & type_ ?~ SwaggerString
133190 & format ?~ T.pack fmt
134191
135192-- | Format @"date"@ corresponds to @yyyy-mm-dd@ format.
136193instance ToParamSchema Day where
137194 toParamSchema _ = timeParamSchema "date"
138195
196+-- |
197+-- >>> toParamSchema (Proxy :: Proxy TimeOfDay) ^. format
198+-- Just "hh:MM:ss"
199+instance ToParamSchema TimeOfDay where
200+ toParamSchema _ = timeParamSchema "hh:MM:ss"
201+
139202-- |
140203-- >>> toParamSchema (Proxy :: Proxy LocalTime) ^. format
141204-- Just "yyyy-mm-ddThh:MM:ss"
@@ -155,7 +218,7 @@ instance ToParamSchema UTCTime where
155218 toParamSchema _ = timeParamSchema "yyyy-mm-ddThh:MM:ssZ"
156219
157220instance ToParamSchema NominalDiffTime where
158− toParamSchema _ = toParamSchema (Proxy :: Proxy Integer)
221+ toParamSchema _ = toParamSchema (Proxy :: Proxy Pico)
159222
160223instance ToParamSchema T.Text where
161224 toParamSchema _ = toParamSchema (Proxy :: Proxy String)
@@ -163,6 +226,28 @@ instance ToParamSchema T.Text where
163226instance ToParamSchema TL.Text where
164227 toParamSchema _ = toParamSchema (Proxy :: Proxy String)
165228
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+
166251instance ToParamSchema All where toParamSchema _ = toParamSchema (Proxy :: Proxy Bool)
167252instance ToParamSchema Any where toParamSchema _ = toParamSchema (Proxy :: Proxy Bool)
168253instance ToParamSchema a => ToParamSchema (Sum a) where toParamSchema _ = toParamSchema (Proxy :: Proxy a)
@@ -171,11 +256,18 @@ instance ToParamSchema a => ToParamSchema (First a) where toParamSchema _ = to
171256instance ToParamSchema a => ToParamSchema (Last a) where toParamSchema _ = toParamSchema (Proxy :: Proxy a)
172257instance ToParamSchema a => ToParamSchema (Dual a) where toParamSchema _ = toParamSchema (Proxy :: Proxy a)
173258
259+instance ToParamSchema a => ToParamSchema (Identity a) where toParamSchema _ = toParamSchema (Proxy :: Proxy a)
260+
174261instance ToParamSchema a => ToParamSchema [a] where
175262 toParamSchema _ = mempty
176− & type_ .~ SwaggerArray
263+ & type_ ?~ SwaggerArray
177264 & items ?~ SwaggerItemsPrimitive Nothing (toParamSchema (Proxy :: Proxy a))
178265
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+
179271instance ToParamSchema a => ToParamSchema (Set a) where
180272 toParamSchema _ = toParamSchema (Proxy :: Proxy [a])
181273 & uniqueItems ?~ True
@@ -188,20 +280,25 @@ instance ToParamSchema a => ToParamSchema (HashSet a) where
188280-- "{\"type\":\"string\",\"enum\":[\"_\"]}"
189281instance ToParamSchema () where
190282 toParamSchema _ = mempty
191− & type_ .~ SwaggerString
283+ & type_ ?~ SwaggerString
192284 & enum_ ?~ ["_"]
193285
286+instance ToParamSchema UUID where
287+ toParamSchema _ = mempty
288+ & type_ ?~ SwaggerString
289+ & format ?~ "uuid"
290+
194291-- | A configurable generic @'ParamSchema'@ creator.
195292--
196293-- >>> :set -XDeriveGeneric
197294-- >>> data Color = Red | Blue deriving Generic
198295-- >>> encode $ genericToParamSchema defaultSchemaOptions (Proxy :: Proxy Color)
199296-- "{\"type\":\"string\",\"enum\":[\"Red\",\"Blue\"]}"
200−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
201298genericToParamSchema opts _ = gtoParamSchema opts (Proxy :: Proxy (Rep a)) mempty
202299
203300class GToParamSchema (f :: * -> *) where
204− gtoParamSchema :: SchemaOptions -> proxy f -> ParamSchema t -> ParamSchema t
301+ gtoParamSchema :: SchemaOptions -> Proxy f -> ParamSchema t -> ParamSchema t
205302
206303instance GToParamSchema f => GToParamSchema (D1 d f) where
207304 gtoParamSchema opts _ = gtoParamSchema opts (Proxy :: Proxy f)
@@ -219,14 +316,14 @@ instance (GEnumParamSchema f, GEnumParamSchema g) => GToParamSchema (f :+: g) wh
219316 gtoParamSchema opts _ = genumParamSchema opts (Proxy :: Proxy (f :+: g))
220317
221318class GEnumParamSchema (f :: * -> *) where
222− genumParamSchema :: SchemaOptions -> proxy f -> ParamSchema t -> ParamSchema t
319+ genumParamSchema :: SchemaOptions -> Proxy f -> ParamSchema t -> ParamSchema t
223320
224321instance (GEnumParamSchema f, GEnumParamSchema g) => GEnumParamSchema (f :+: g) where
225322 genumParamSchema opts _ = genumParamSchema opts (Proxy :: Proxy f) . genumParamSchema opts (Proxy :: Proxy g)
226323
227324instance Constructor c => GEnumParamSchema (C1 c U1) where
228325 genumParamSchema opts _ s = s
229− & type_ .~ SwaggerString
326+ & type_ ?~ SwaggerString
230327 & enum_ %~ addEnumValue tag
231328 where
232329 tag = toJSON (constructorTagModifier opts (conName (Proxy3 :: Proxy3 c f p)))
@@ -236,3 +333,5 @@ instance Constructor c => GEnumParamSchema (C1 c U1) where
236333
237334data Proxy3 a b c = Proxy3
238335
336+-- $setup
337+-- >>> import Data.Aeson (encode)
src/Data/Swagger/Internal/Schema.hs+413−97
@@ -1,7 +1,10 @@
1+{-# LANGUAGE CPP #-}
2+{-# LANGUAGE ConstraintKinds #-}
13{-# LANGUAGE DefaultSignatures #-}
24{-# LANGUAGE FlexibleContexts #-}
35{-# LANGUAGE FlexibleInstances #-}
46{-# LANGUAGE KindSignatures #-}
7+{-# LANGUAGE DataKinds #-}
58{-# LANGUAGE OverloadedLists #-}
69{-# LANGUAGE OverloadedStrings #-}
710{-# LANGUAGE PackageImports #-}
@@ -11,39 +14,69 @@
1114{-# LANGUAGE TypeFamilies #-}
1215{-# LANGUAGE TypeOperators #-}
1316{-# 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
24+#include "overlapping-compat.h"
1425module Data.Swagger.Internal.Schema where
1526
27+import Prelude ()
28+import Prelude.Compat
29+
1630import Control.Lens
1731import Data.Data.Lens (template)
1832
1933import Control.Monad
2034import Control.Monad.Writer
21−import Data.Aeson
35+import Data.Aeson (ToJSON (..), ToJSONKey (..), ToJSONKeyFunction (..), Value (..), Object(..))
2236import Data.Char
2337import Data.Data (Data)
2438import Data.Foldable (traverse_)
2539import Data.HashMap.Strict (HashMap)
2640import qualified Data.HashMap.Strict as HashMap
27−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
2844import Data.Int
2945import Data.IntSet (IntSet)
3046import Data.IntMap (IntMap)
47+import Data.List.NonEmpty.Compat (NonEmpty)
3148import Data.Map (Map)
32−import Data.Monoid
3349import Data.Proxy
3450import Data.Scientific (Scientific)
51+import Data.Fixed (Fixed, HasResolution, Pico)
3552import Data.Set (Set)
3653import qualified Data.Text as T
3754import qualified Data.Text.Lazy as TL
3855import 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)
3962import Data.Word
4063import GHC.Generics
64+import qualified Data.UUID.Types as UUID
4165
4266import Data.Swagger.Declare
4367import Data.Swagger.Internal
4468import Data.Swagger.Internal.ParamSchema (ToParamSchema(..))
45−import Data.Swagger.Lens
69+import Data.Swagger.Lens hiding (name, schema)
70+import qualified Data.Swagger.Lens as Swagger
4671import Data.Swagger.SchemaOptions
72+import Data.Swagger.Internal.TypeShape
73+
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(..))
79+#endif
4780
4881unnamed :: Schema -> NamedSchema
4982unnamed schema = NamedSchema Nothing schema
@@ -69,19 +102,21 @@ rename name (NamedSchema _ schema) = NamedSchema name schema
69102-- {-\# LANGUAGE OverloadedLists \#-} -- allows to write 'Map' and 'HashMap' as lists
70103--
71104-- import Control.Lens
105+-- import Data.Proxy
106+-- import Data.Swagger
72107--
73108-- data Coord = Coord { x :: Double, y :: Double }
74109--
75110-- instance ToSchema Coord where
76−-- declareNamedSchema = pure (Just \"Coord\", schema)
77−-- where
78−-- schema = mempty
79−-- & type_ .~ SwaggerObject
80−-- & properties .~
81−-- [ (\"x\", toSchemaRef (Proxy :: Proxy Double))
82−-- , (\"y\", toSchemaRef (Proxy :: Proxy Double))
83−-- ]
84−-- & 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\" ]
85120-- @
86121--
87122-- Instead of manually writing your @'ToSchema'@ instance you can
@@ -107,12 +142,17 @@ class ToSchema a where
107142 -- together with all used definitions.
108143 -- Note that the schema itself is included in definitions
109144 -- only if it is recursive (and thus needs its definition in scope).
110− declareNamedSchema :: proxy a -> Declare (Definitions Schema) NamedSchema
111− 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
112148 declareNamedSchema = genericDeclareNamedSchema defaultSchemaOptions
113149
150+instance ToSchema TimeOfDay where
151+ declareNamedSchema _ = pure $ named "TimeOfDay" $ timeSchema "hh:MM:ss"
152+ & example ?~ toJSON (TimeOfDay 12 33 15)
153+
114154-- | Convert a type into a schema and declare all used schema definitions.
115−declareSchema :: ToSchema a => proxy a -> Declare (Definitions Schema) Schema
155+declareSchema :: ToSchema a => Proxy a -> Declare (Definitions Schema) Schema
116156declareSchema = fmap _namedSchemaSchema . declareNamedSchema
117157
118158-- | Convert a type into an optionally named schema.
@@ -125,8 +165,8 @@ declareSchema = fmap _namedSchemaSchema . declareNamedSchema
125165-- >>> toNamedSchema (Proxy :: Proxy Day) ^. name
126166-- Just "Day"
127167-- >>> encode (toNamedSchema (Proxy :: Proxy Day) ^. schema)
128−-- "{\"format\":\"date\",\"type\":\"string\"}"
129−toNamedSchema :: ToSchema a => proxy a -> NamedSchema
168+-- "{\"example\":\"2016-07-22\",\"format\":\"date\",\"type\":\"string\"}"
169+toNamedSchema :: ToSchema a => Proxy a -> NamedSchema
130170toNamedSchema = undeclare . declareNamedSchema
131171
132172-- | Get type's schema name according to its @'ToSchema'@ instance.
@@ -136,7 +176,7 @@ toNamedSchema = undeclare . declareNamedSchema
136176--
137177-- >>> schemaName (Proxy :: Proxy UTCTime)
138178-- Just "UTCTime"
139−schemaName :: ToSchema a => proxy a -> Maybe T.Text
179+schemaName :: ToSchema a => Proxy a -> Maybe T.Text
140180schemaName = _namedSchemaName . toNamedSchema
141181
142182-- | Convert a type into a schema.
@@ -146,7 +186,7 @@ schemaName = _namedSchemaName . toNamedSchema
146186--
147187-- >>> encode $ toSchema (Proxy :: Proxy [Day])
148188-- "{\"items\":{\"$ref\":\"#/definitions/Day\"},\"type\":\"array\"}"
149−toSchema :: ToSchema a => proxy a -> Schema
189+toSchema :: ToSchema a => Proxy a -> Schema
150190toSchema = _namedSchemaSchema . toNamedSchema
151191
152192-- | Convert a type into a referenced schema if possible.
@@ -157,7 +197,7 @@ toSchema = _namedSchemaSchema . toNamedSchema
157197--
158198-- >>> encode $ toSchemaRef (Proxy :: Proxy Day)
159199-- "{\"$ref\":\"#/definitions/Day\"}"
160−toSchemaRef :: ToSchema a => proxy a -> Referenced Schema
200+toSchemaRef :: ToSchema a => Proxy a -> Referenced Schema
161201toSchemaRef = undeclare . declareSchemaRef
162202
163203-- | Convert a type into a referenced schema if possible
@@ -167,7 +207,7 @@ toSchemaRef = undeclare . declareSchemaRef
167207-- Schema definitions are typically declared for every referenced schema.
168208-- If @'declareSchemaRef'@ returns a reference, a corresponding schema
169209-- will be declared (regardless of whether it is recusive or not).
170−declareSchemaRef :: ToSchema a => proxy a -> Declare (Definitions Schema) (Referenced Schema)
210+declareSchemaRef :: ToSchema a => Proxy a -> Declare (Definitions Schema) (Referenced Schema)
171211declareSchemaRef proxy = do
172212 case toNamedSchema proxy of
173213 NamedSchema (Just name) schema -> do
@@ -179,7 +219,7 @@ declareSchemaRef proxy = do
179219 -- have already declared it.
180220 -- If we have, we don't need to declare anything for
181221 -- this schema this time and thus simply return the reference.
182− known <- looks (HashMap.member name)
222+ known <- looks (InsOrdHashMap.member name)
183223 when (not known) $ do
184224 declare [(name, schema)]
185225 void $ declareNamedSchema proxy
@@ -198,7 +238,7 @@ inlineSchemasWhen p defs = template %~ deref
198238 where
199239 deref r@(Ref (Reference name))
200240 | p name =
201− case HashMap.lookup name defs of
241+ case InsOrdHashMap.lookup name defs of
202242 Just schema -> Inline (inlineSchemasWhen p defs schema)
203243 Nothing -> r
204244 | otherwise = r
@@ -225,11 +265,11 @@ inlineAllSchemas = inlineSchemasWhen (const True)
225265-- | Convert a type into a schema without references.
226266--
227267-- >>> encode $ toInlinedSchema (Proxy :: Proxy [Day])
228−-- "{\"items\":{\"format\":\"date\",\"type\":\"string\"},\"type\":\"array\"}"
268+-- "{\"items\":{\"example\":\"2016-07-22\",\"format\":\"date\",\"type\":\"string\"},\"type\":\"array\"}"
229269--
230270-- __WARNING:__ @'toInlinedSchema'@ will produce infinite schema
231271-- when inlining recursive schemas.
232−toInlinedSchema :: ToSchema a => proxy a -> Schema
272+toInlinedSchema :: ToSchema a => Proxy a -> Schema
233273toInlinedSchema proxy = inlineAllSchemas defs schema
234274 where
235275 (defs, schema) = runDeclare (declareSchema proxy) mempty
@@ -240,7 +280,7 @@ inlineNonRecursiveSchemas :: Data s => (Definitions Schema) -> s -> s
240280inlineNonRecursiveSchemas defs = inlineSchemasWhen nonRecursive defs
241281 where
242282 nonRecursive name =
243− case HashMap.lookup name defs of
283+ case InsOrdHashMap.lookup name defs of
244284 Just schema -> name `notElem` execDeclare (usedNames schema) mempty
245285 Nothing -> False
246286
@@ -252,22 +292,141 @@ inlineNonRecursiveSchemas defs = inlineSchemasWhen nonRecursive defs
252292 seen <- looks (name `elem`)
253293 when (not seen) $ do
254294 declare [name]
255− traverse_ usedNames (HashMap.lookup name defs)
295+ traverse_ usedNames (InsOrdHashMap.lookup name defs)
256296 Inline subschema -> usedNames subschema
257297
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+
258416class GToSchema (f :: * -> *) where
259− gdeclareNamedSchema :: SchemaOptions -> proxy f -> Schema -> Declare (Definitions Schema) NamedSchema
417+ gdeclareNamedSchema :: SchemaOptions -> Proxy f -> Schema -> Declare (Definitions Schema) NamedSchema
260418
261−instance {-# OVERLAPPABLE #-} ToSchema a => ToSchema [a] where
419+instance OVERLAPPABLE_ ToSchema a => ToSchema [a] where
262420 declareNamedSchema _ = do
263421 ref <- declareSchemaRef (Proxy :: Proxy a)
264422 return $ unnamed $ mempty
265− & type_ .~ SwaggerArray
423+ & type_ ?~ SwaggerArray
266424 & items ?~ SwaggerItemsObject ref
267425
268−instance {-# OVERLAPPING #-} ToSchema String where declareNamedSchema = plain . paramSchemaToSchema
426+instance OVERLAPPING_ ToSchema String where declareNamedSchema = plain . paramSchemaToSchema
269427instance ToSchema Bool where declareNamedSchema = plain . paramSchemaToSchema
270428instance ToSchema Integer where declareNamedSchema = plain . paramSchemaToSchema
429+instance ToSchema Natural where declareNamedSchema = plain . paramSchemaToSchema
271430instance ToSchema Int where declareNamedSchema = plain . paramSchemaToSchema
272431instance ToSchema Int8 where declareNamedSchema = plain . paramSchemaToSchema
273432instance ToSchema Int16 where declareNamedSchema = plain . paramSchemaToSchema
@@ -279,11 +438,16 @@ instance ToSchema Word16 where declareNamedSchema = plain . paramSchemaToSchema
279438instance ToSchema Word32 where declareNamedSchema = plain . paramSchemaToSchema
280439instance ToSchema Word64 where declareNamedSchema = plain . paramSchemaToSchema
281440
282−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+
283445instance ToSchema Scientific where declareNamedSchema = plain . paramSchemaToSchema
284446instance ToSchema Double where declareNamedSchema = plain . paramSchemaToSchema
285447instance ToSchema Float where declareNamedSchema = plain . paramSchemaToSchema
286448
449+instance HasResolution a => ToSchema (Fixed a) where declareNamedSchema = plain . paramSchemaToSchema
450+
287451instance ToSchema a => ToSchema (Maybe a) where
288452 declareNamedSchema _ = declareNamedSchema (Proxy :: Proxy a)
289453
@@ -292,6 +456,11 @@ instance (ToSchema a, ToSchema b) => ToSchema (Either a b)
292456instance ToSchema () where
293457 declareNamedSchema _ = pure (NamedSchema Nothing nullarySchema)
294458
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+
295464instance (ToSchema a, ToSchema b) => ToSchema (a, b)
296465instance (ToSchema a, ToSchema b, ToSchema c) => ToSchema (a, b, c)
297466instance (ToSchema a, ToSchema b, ToSchema c, ToSchema d) => ToSchema (a, b, c, d)
@@ -301,46 +470,81 @@ instance (ToSchema a, ToSchema b, ToSchema c, ToSchema d, ToSchema e, ToSchema f
301470
302471timeSchema :: T.Text -> Schema
303472timeSchema fmt = mempty
304− & type_ .~ SwaggerString
473+ & type_ ?~ SwaggerString
305474 & format ?~ fmt
306475
307476-- | Format @"date"@ corresponds to @yyyy-mm-dd@ format.
308477instance ToSchema Day where
309− declareNamedSchema _ = pure $ named "Day" (timeSchema "date")
478+ declareNamedSchema _ = pure $ named "Day" $ timeSchema "date"
479+ & example ?~ toJSON (fromGregorian 2016 7 22)
310480
311481-- |
312482-- >>> toSchema (Proxy :: Proxy LocalTime) ^. format
313483-- Just "yyyy-mm-ddThh:MM:ss"
314484instance ToSchema LocalTime where
315− 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))
316487
317488-- | Format @"date"@ corresponds to @yyyy-mm-ddThh:MM:ss(Z|+hh:MM)@ format.
318489instance ToSchema ZonedTime where
319490 declareNamedSchema _ = pure $ named "ZonedTime" $ timeSchema "date-time"
491+ & example ?~ toJSON (ZonedTime (LocalTime (fromGregorian 2016 7 22) (TimeOfDay 7 40 0)) (hoursToTimeZone 3))
320492
321493instance ToSchema NominalDiffTime where
322− declareNamedSchema _ = declareNamedSchema (Proxy :: Proxy Integer)
494+ declareNamedSchema _ = declareNamedSchema (Proxy :: Proxy Pico)
323495
324496-- |
325497-- >>> toSchema (Proxy :: Proxy UTCTime) ^. format
326498-- Just "yyyy-mm-ddThh:MM:ssZ"
327499instance ToSchema UTCTime where
328− 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)
329502
330503instance ToSchema T.Text where declareNamedSchema = plain . paramSchemaToSchema
331504instance ToSchema TL.Text where declareNamedSchema = plain . paramSchemaToSchema
332505
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+
333520instance ToSchema IntSet where declareNamedSchema _ = declareNamedSchema (Proxy :: Proxy (Set Int))
334521
335522-- | NOTE: This schema does not account for the uniqueness of keys.
336523instance ToSchema a => ToSchema (IntMap a) where
337524 declareNamedSchema _ = declareNamedSchema (Proxy :: Proxy [(Int, a)])
338525
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+
339543instance ToSchema a => ToSchema (Map String a) where
340544 declareNamedSchema _ = do
341− schema <- declareSchema (Proxy :: Proxy a)
545+ schema <- declareSchemaRef (Proxy :: Proxy a)
342546 return $ unnamed $ mempty
343− & type_ .~ SwaggerObject
547+ & type_ ?~ SwaggerObject
344548 & additionalProperties ?~ schema
345549
346550instance ToSchema a => ToSchema (Map T.Text a) where declareNamedSchema _ = declareNamedSchema (Proxy :: Proxy (Map String a))
@@ -350,6 +554,19 @@ instance ToSchema a => ToSchema (HashMap String a) where declareNamedSchema _ =
350554instance ToSchema a => ToSchema (HashMap T.Text a) where declareNamedSchema _ = declareNamedSchema (Proxy :: Proxy (Map String a))
351555instance ToSchema a => ToSchema (HashMap TL.Text a) where declareNamedSchema _ = declareNamedSchema (Proxy :: Proxy (Map String a))
352556
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+
353570instance ToSchema a => ToSchema (Set a) where
354571 declareNamedSchema _ = do
355572 schema <- declareSchema (Proxy :: Proxy [a])
@@ -358,6 +575,13 @@ instance ToSchema a => ToSchema (Set a) where
358575
359576instance ToSchema a => ToSchema (HashSet a) where declareNamedSchema _ = declareNamedSchema (Proxy :: Proxy (Set a))
360577
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+
361585instance ToSchema All where declareNamedSchema = plain . paramSchemaToSchema
362586instance ToSchema Any where declareNamedSchema = plain . paramSchemaToSchema
363587
@@ -367,82 +591,161 @@ instance ToSchema a => ToSchema (First a) where declareNamedSchema _ = unname
367591instance ToSchema a => ToSchema (Last a) where declareNamedSchema _ = unname <$> declareNamedSchema (Proxy :: Proxy a)
368592instance ToSchema a => ToSchema (Dual a) where declareNamedSchema _ = unname <$> declareNamedSchema (Proxy :: Proxy a)
369593
594+instance ToSchema a => ToSchema (Identity a) where declareNamedSchema _ = declareNamedSchema (Proxy :: Proxy a)
595+
370596-- | Default schema for @'Bounded'@, @'Integral'@ types.
371597--
372598-- >>> encode $ toSchemaBoundedIntegral (Proxy :: Proxy Int16)
373599-- "{\"maximum\":32767,\"minimum\":-32768,\"type\":\"integer\"}"
374−toSchemaBoundedIntegral :: forall a proxy. (Bounded a, Integral a) => proxy a -> Schema
600+toSchemaBoundedIntegral :: forall a. (Bounded a, Integral a) => Proxy a -> Schema
375601toSchemaBoundedIntegral _ = mempty
376− & type_ .~ SwaggerInteger
602+ & type_ ?~ SwaggerInteger
377603 & minimum_ ?~ fromInteger (toInteger (minBound :: a))
378604 & maximum_ ?~ fromInteger (toInteger (maxBound :: a))
379605
380606-- | Default generic named schema for @'Bounded'@, @'Integral'@ types.
381−genericToNamedSchemaBoundedIntegral :: forall a d f proxy.
607+genericToNamedSchemaBoundedIntegral :: forall a d f.
382608 ( Bounded a, Integral a
383609 , Generic a, Rep a ~ D1 d f, Datatype d)
384− => SchemaOptions -> proxy a -> NamedSchema
610+ => SchemaOptions -> Proxy a -> NamedSchema
385611genericToNamedSchemaBoundedIntegral opts proxy
386− = 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
387668
388669-- | A configurable generic @'Schema'@ creator.
389−genericDeclareSchema :: (Generic a, GToSchema (Rep a)) => SchemaOptions -> proxy a -> Declare (Definitions Schema) Schema
390−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
391673
392674-- | A configurable generic @'NamedSchema'@ creator.
393675-- This function applied to @'defaultSchemaOptions'@
394676-- is used as the default for @'declareNamedSchema'@
395677-- when the type is an instance of @'Generic'@.
396−genericDeclareNamedSchema :: forall a proxy. (Generic a, GToSchema (Rep a)) => SchemaOptions -> proxy a -> Declare (Definitions Schema) NamedSchema
397−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
681+
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
398688
399−gdatatypeSchemaName :: forall proxy d. Datatype d => SchemaOptions -> proxy d -> Maybe T.Text
400−gdatatypeSchemaName opts _ = case name of
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
401705 (c:_) | isAlpha c && isUpper c -> Just (T.pack name)
402706 _ -> Nothing
403707 where
404− name = datatypeNameModifier opts (datatypeName (Proxy3 :: Proxy3 d f a))
708+ orig = datatypeName (Proxy3 :: Proxy3 d f a)
709+ name = datatypeNameModifier opts orig
405710
406711-- | Lift a plain @'ParamSchema'@ into a model @'NamedSchema'@.
407−paramSchemaToNamedSchema :: forall a d f proxy.
408− (ToParamSchema a, Generic a, Rep a ~ D1 d f, Datatype d)
409− => SchemaOptions -> proxy a -> NamedSchema
410−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)
411715
412716-- | Lift a plain @'ParamSchema'@ into a model @'Schema'@.
413−paramSchemaToSchema :: forall a proxy. ToParamSchema a => proxy a -> Schema
414−paramSchemaToSchema _ = mempty & paramSchema .~ toParamSchema (Proxy :: Proxy a)
717+paramSchemaToSchema :: ToParamSchema a => Proxy a -> Schema
718+paramSchemaToSchema proxy = mempty & paramSchema .~ toParamSchema proxy
415719
416720nullarySchema :: Schema
417721nullarySchema = mempty
418− & type_ .~ SwaggerArray
419− & enum_ ?~ [ toJSON () ]
722+ & type_ ?~ SwaggerArray
420723 & items ?~ SwaggerItemsArray []
421724
422−gtoNamedSchema :: GToSchema f => SchemaOptions -> proxy f -> NamedSchema
725+gtoNamedSchema :: GToSchema f => SchemaOptions -> Proxy f -> NamedSchema
423726gtoNamedSchema opts proxy = undeclare $ gdeclareNamedSchema opts proxy mempty
424727
425−gdeclareSchema :: GToSchema f => SchemaOptions -> proxy f -> Declare (Definitions Schema) Schema
728+gdeclareSchema :: GToSchema f => SchemaOptions -> Proxy f -> Declare (Definitions Schema) Schema
426729gdeclareSchema opts proxy = _namedSchemaSchema <$> gdeclareNamedSchema opts proxy mempty
427730
428731instance (GToSchema f, GToSchema g) => GToSchema (f :*: g) where
429732 gdeclareNamedSchema opts _ schema = do
430− NamedSchema _ gschema <- gdeclareNamedSchema opts (Proxy :: Proxy g) schema
431− gdeclareNamedSchema opts (Proxy :: Proxy f) gschema
733+ NamedSchema _ gschema <- gdeclareNamedSchema opts (Proxy :: Proxy f) schema
734+ gdeclareNamedSchema opts (Proxy :: Proxy g) gschema
432735
433736instance (Datatype d, GToSchema f) => GToSchema (D1 d f) where
434737 gdeclareNamedSchema opts _ s = rename name <$> gdeclareNamedSchema opts (Proxy :: Proxy f) s
435738 where
436739 name = gdatatypeSchemaName opts (Proxy :: Proxy d)
437740
438−instance {-# OVERLAPPABLE #-} GToSchema f => GToSchema (C1 c f) where
741+instance OVERLAPPABLE_ GToSchema f => GToSchema (C1 c f) where
439742 gdeclareNamedSchema opts _ = gdeclareNamedSchema opts (Proxy :: Proxy f)
440743
441−instance {-# OVERLAPPING #-} Constructor c => GToSchema (C1 c U1) where
744+instance OVERLAPPING_ Constructor c => GToSchema (C1 c U1) where
442745 gdeclareNamedSchema = gdeclareNamedSumSchema
443746
444747-- | Single field constructor.
445−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
446749 gdeclareNamedSchema opts _ s
447750 | unwrapUnaryRecords opts = fieldSchema
448751 | otherwise =
@@ -456,7 +759,7 @@ instance (Selector s, GToSchema f) => GToSchema (C1 c (S1 s f)) where
456759 recordSchema = gdeclareNamedSchema opts (Proxy :: Proxy (S1 s f)) s
457760 fieldSchema = gdeclareNamedSchema opts (Proxy :: Proxy f) s
458761
459−gdeclareSchemaRef :: GToSchema a => SchemaOptions -> proxy a -> Declare (Definitions Schema) (Referenced Schema)
762+gdeclareSchemaRef :: GToSchema a => SchemaOptions -> Proxy a -> Declare (Definitions Schema) (Referenced Schema)
460763gdeclareSchemaRef opts proxy = do
461764 case gtoNamedSchema opts proxy of
462765 NamedSchema (Just name) schema -> do
@@ -468,16 +771,16 @@ gdeclareSchemaRef opts proxy = do
468771 -- have already declared it.
469772 -- If we have, we don't need to declare anything for
470773 -- this schema this time and thus simply return the reference.
471− known <- looks (HashMap.member name)
774+ known <- looks (InsOrdHashMap.member name)
472775 when (not known) $ do
473776 declare [(name, schema)]
474777 void $ gdeclareNamedSchema opts proxy mempty
475778 return $ Ref (Reference name)
476779 _ -> Inline <$> gdeclareSchema opts proxy
477780
478−appendItem :: Referenced Schema -> Maybe (SwaggerItems Schema) -> Maybe (SwaggerItems Schema)
781+appendItem :: Referenced Schema -> Maybe (SwaggerItems 'SwaggerKindSchema) -> Maybe (SwaggerItems 'SwaggerKindSchema)
479782appendItem x Nothing = Just (SwaggerItemsArray [x])
480−appendItem x (Just (SwaggerItemsArray xs)) = Just (SwaggerItemsArray (x:xs))
783+appendItem x (Just (SwaggerItemsArray xs)) = Just (SwaggerItemsArray (xs ++ [x]))
481784appendItem _ _ = error "GToSchema.appendItem: cannot append to SwaggerItemsObject"
482785
483786withFieldSchema :: forall proxy s f. (Selector s, GToSchema f) =>
@@ -487,35 +790,40 @@ withFieldSchema opts _ isRequiredField schema = do
487790 return $
488791 if T.null fname
489792 then schema
490− & type_ .~ SwaggerArray
793+ & type_ ?~ SwaggerArray
491794 & items %~ appendItem ref
795+ & maxItems %~ Just . maybe 1 (+1) -- increment maxItems
796+ & minItems %~ Just . maybe 1 (+1) -- increment minItems
492797 else schema
493− & type_ .~ SwaggerObject
798+ & type_ ?~ SwaggerObject
494799 & properties . at fname ?~ ref
495800 & if isRequiredField
496− then required %~ (fname :)
801+ then required %~ (++ [fname])
497802 else id
498803 where
499804 fname = T.pack (fieldLabelModifier opts (selName (Proxy3 :: Proxy3 s f p)))
500805
501806-- | Optional record fields.
502−instance {-# OVERLAPPING #-} (Selector s, ToSchema c) => GToSchema (S1 s (K1 i (Maybe c))) where
807+instance OVERLAPPING_ (Selector s, ToSchema c) => GToSchema (S1 s (K1 i (Maybe c))) where
503808 gdeclareNamedSchema opts _ = fmap unnamed . withFieldSchema opts (Proxy2 :: Proxy2 s (K1 i (Maybe c))) False
504809
505810-- | Record fields.
506−instance {-# OVERLAPPABLE #-} (Selector s, GToSchema f) => GToSchema (S1 s f) where
811+instance OVERLAPPABLE_ (Selector s, GToSchema f) => GToSchema (S1 s f) where
507812 gdeclareNamedSchema opts _ = fmap unnamed . withFieldSchema opts (Proxy2 :: Proxy2 s f) True
508813
509−instance {-# OVERLAPPING #-} ToSchema c => GToSchema (K1 i (Maybe c)) where
814+instance OVERLAPPING_ ToSchema c => GToSchema (K1 i (Maybe c)) where
510815 gdeclareNamedSchema _ _ _ = declareNamedSchema (Proxy :: Proxy c)
511816
512−instance {-# OVERLAPPABLE #-} ToSchema c => GToSchema (K1 i c) where
817+instance OVERLAPPABLE_ ToSchema c => GToSchema (K1 i c) where
513818 gdeclareNamedSchema _ _ _ = declareNamedSchema (Proxy :: Proxy c)
514819
515−instance (GSumToSchema f, GSumToSchema g) => GToSchema (f :+: g) where
820+instance ( GSumToSchema f
821+ , GSumToSchema g
822+ ) => GToSchema (f :+: g)
823+ where
516824 gdeclareNamedSchema = gdeclareNamedSumSchema
517825
518−gdeclareNamedSumSchema :: GSumToSchema f => SchemaOptions -> proxy f -> Schema -> Declare (Definitions Schema) NamedSchema
826+gdeclareNamedSumSchema :: GSumToSchema f => SchemaOptions -> Proxy f -> Schema -> Declare (Definitions Schema) NamedSchema
519827gdeclareNamedSumSchema opts proxy s
520828 | allNullaryToStringTag opts && allNullary = pure $ unnamed (toStringTag sumSchema)
521829 | otherwise = (unnamed . fst) <$> runWriterT declareSumSchema
@@ -524,30 +832,34 @@ gdeclareNamedSumSchema opts proxy s
524832 (sumSchema, All allNullary) = undeclare (runWriterT declareSumSchema)
525833
526834 toStringTag schema = mempty
527− & type_ .~ SwaggerString
528− & enum_ ?~ map toJSON (schema ^.. properties.ifolded.asIndex)
835+ & type_ ?~ SwaggerString
836+ & enum_ ?~ map toJSON (schema ^.. properties.ifolded.asIndex)
529837
530838type AllNullary = All
531839
532−class GSumToSchema f where
533− 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
534842
535843instance (GSumToSchema f, GSumToSchema g) => GSumToSchema (f :+: g) where
536− gsumToSchema opts _ = gsumToSchema opts (Proxy :: Proxy f) <=< gsumToSchema opts (Proxy :: Proxy g)
537−
538−gsumConToSchema :: forall c f proxy. (GToSchema (C1 c f), Constructor c) =>
539− SchemaOptions -> proxy (C1 c f) -> Schema -> Declare (Definitions Schema) Schema
540−gsumConToSchema opts _ schema = do
541− ref <- gdeclareSchemaRef opts (Proxy :: Proxy (C1 c f))
542− return $ schema
543− & type_ .~ SwaggerObject
544− & properties . at tag ?~ ref
545− & maxProperties ?~ 1
546− & minProperties ?~ 1
844+ gsumToSchema opts _ = gsumToSchema opts (Proxy :: Proxy f) >=> gsumToSchema opts (Proxy :: Proxy g)
845+
846+gsumConToSchemaWith :: forall c f. (GToSchema (C1 c f), Constructor c) =>
847+ Referenced Schema -> SchemaOptions -> Proxy (C1 c f) -> Schema -> Schema
848+gsumConToSchemaWith ref opts _ schema = schema
849+ & type_ ?~ SwaggerObject
850+ & properties . at tag ?~ ref
851+ & maxProperties ?~ 1
852+ & minProperties ?~ 1
547853 where
548854 tag = T.pack (constructorTagModifier opts (conName (Proxy3 :: Proxy3 c f p)))
549855
550−instance {-# OVERLAPPABLE #-} (Constructor c, GToSchema f) => GSumToSchema (C1 c f) where
856+gsumConToSchema :: (GToSchema (C1 c f), Constructor c) =>
857+ SchemaOptions -> Proxy (C1 c f) -> Schema -> Declare (Definitions Schema) Schema
858+gsumConToSchema opts proxy schema = do
859+ ref <- gdeclareSchemaRef opts proxy
860+ return $ gsumConToSchemaWith ref opts proxy schema
861+
862+instance OVERLAPPABLE_ (Constructor c, GToSchema f) => GSumToSchema (C1 c f) where
551863 gsumToSchema opts proxy schema = do
552864 tell (All False)
553865 lift $ gsumConToSchema opts proxy schema
@@ -558,9 +870,13 @@ instance (Constructor c, Selector s, GToSchema f) => GSumToSchema (C1 c (S1 s f)
558870 lift $ gsumConToSchema opts proxy schema
559871
560872instance Constructor c => GSumToSchema (C1 c U1) where
561− gsumToSchema opts proxy = lift . gsumConToSchema opts proxy
873+ gsumToSchema opts proxy = pure . gsumConToSchemaWith (Inline nullarySchema) opts proxy
562874
563875data Proxy2 a b = Proxy2
564876
565877data Proxy3 a b c = Proxy3
566878
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+13−47
@@ -6,8 +6,9 @@
66{-# LANGUAGE TypeOperators #-}
77module Data.Swagger.Internal.Utils where
88
9−import Control.Arrow (first)
10−import Control.Applicative
9+import Prelude ()
10+import Prelude.Compat
11+
1112import Control.Lens ((&), (%~))
1213import Control.Lens.TH
1314import Data.Aeson
@@ -17,12 +18,13 @@ import Data.Data
1718import Data.Hashable (Hashable)
1819import Data.HashMap.Strict (HashMap)
1920import qualified Data.HashMap.Strict as HashMap
21+import Data.HashMap.Strict.InsOrd (InsOrdHashMap)
22+import qualified Data.HashMap.Strict.InsOrd as InsOrdHashMap
2023import Data.Map (Map)
21−import Data.Monoid
24+import Data.Set (Set)
2225import Data.Text (Text)
2326import GHC.Generics
2427import Language.Haskell.TH (mkName)
25−import Text.Read (readMaybe)
2628
2729swaggerFieldRules :: LensRules
2830swaggerFieldRules = defaultFieldRules & lensField %~ swaggerFieldNamer
@@ -41,6 +43,7 @@ swaggerFieldRules = defaultFieldRules & lensField %~ swaggerFieldNamer
4143 fixName' "minimum" = "minimum_" -- Prelude conflict
4244 fixName' "maximum" = "maximum_" -- Prelude conflict
4345 fixName' "enum" = "enum_" -- Control.Lens conflict
46+ fixName' "head" = "head_" -- Prelude conflict
4447 fixName' n = n
4548
4649gunfoldEnum :: String -> [a] -> (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c a
@@ -48,17 +51,6 @@ gunfoldEnum tname xs _k z c = case lookup (constrIndex c) (zip [1..] xs) of
4851 Just x -> z x
4952 Nothing -> error $ "Data.Data.gunfold: Constructor " ++ show c ++ " is not of type " ++ tname ++ "."
5053
51−hashMapMapKeys :: (Eq k', Hashable k') => (k -> k') -> HashMap k v -> HashMap k' v
52−hashMapMapKeys f = HashMap.fromList . map (first f) . HashMap.toList
53−
54−hashMapTraverseKeys :: (Eq k', Hashable k', Applicative f) => (k -> f k') -> HashMap k v -> f (HashMap k' v)
55−hashMapTraverseKeys f = fmap HashMap.fromList . traverse g . HashMap.toList
56− where
57− g (x, y) = (\a -> (a, y)) <$> f x
58−
59−hashMapReadKeys :: (Eq k, Read k, Hashable k, Alternative f) => HashMap String v -> f (HashMap k v)
60−hashMapReadKeys = hashMapTraverseKeys (maybe empty pure . readMaybe)
61−
6254jsonPrefix :: String -> Options
6355jsonPrefix prefix = defaultOptions
6456 { fieldLabelModifier = modifier . drop 1
@@ -80,40 +72,10 @@ parseOneOf xs js =
8072 where
8173 ys = zip (map toJSON xs) xs
8274
83−omitEmptiesExcept :: (Text -> Value -> Bool) -> Value -> Value
84−omitEmptiesExcept f (Object o) = Object (HashMap.filterWithKey nonEmpty o)
85− where
86− nonEmpty k js = f k js || (js /= Object mempty) && (js /= Array mempty) && (js /= Null)
87−omitEmptiesExcept _ js = js
88−
89−omitEmpties :: Value -> Value
90−omitEmpties = omitEmptiesExcept (\_ _ -> False)
91−
92−genericToJSONWithSub :: (Generic a, GToJSON (Rep a)) => Text -> Options -> a -> Value
93−genericToJSONWithSub sub opts x =
94− case genericToJSON opts x of
95− Object o ->
96− case HashMap.lookup sub o of
97− Just so -> Object (HashMap.delete sub o) <+> so
98− Nothing -> Object o -- no subjson, leaving object as is
99− _ -> error "genericToJSONWithSub: subjson is not an object"
100−
101−genericParseJSONWithSub :: (Generic a, GFromJSON (Rep a)) => Text -> Options -> Value -> Parser a
102−genericParseJSONWithSub sub opts js@(Object o)
103− = genericParseJSON opts js -- try without subjson
104− <|> genericParseJSON opts js' -- try with subjson
105− where
106− js' = Object (HashMap.insert sub (Object o) o)
107−genericParseJSONWithSub _ _ _ = error "genericParseJSONWithSub: given json is not an object"
108−
10975(<+>) :: Value -> Value -> Value
11076Object x <+> Object y = Object (x <> y)
11177_ <+> _ = error "<+>: merging non-objects"
11278
113−withDefaults :: (Value -> Parser a) -> [Pair] -> Value -> Parser a
114−withDefaults parser defs js@(Object _) = parser (js <+> object defs)
115−withDefaults _ _ _ = empty
116−
11779genericMempty :: (Generic a, GMonoid (Rep a)) => a
11880genericMempty = to gmempty
11981
@@ -149,12 +111,17 @@ class SwaggerMonoid m where
149111 swaggerMappend = mappend
150112
151113instance SwaggerMonoid [a]
114+instance Ord a => SwaggerMonoid (Set a)
152115instance Ord k => SwaggerMonoid (Map k v)
153116
154−instance {-# OVERLAPPABLE #-} (Eq k, Hashable k) => SwaggerMonoid (HashMap k v) where
117+instance (Eq k, Hashable k) => SwaggerMonoid (HashMap k v) where
155118 swaggerMempty = mempty
156119 swaggerMappend = HashMap.unionWith (\_old new -> new)
157120
121+instance (Eq k, Hashable k) => SwaggerMonoid (InsOrdHashMap k v) where
122+ swaggerMempty = mempty
123+ swaggerMappend = InsOrdHashMap.unionWith (\_old new -> new)
124+
158125instance SwaggerMonoid Text where
159126 swaggerMempty = mempty
160127 swaggerMappend x "" = x
@@ -164,4 +131,3 @@ instance SwaggerMonoid (Maybe a) where
164131 swaggerMempty = Nothing
165132 swaggerMappend x Nothing = x
166133 swaggerMappend _ y = y
167−
src/Data/Swagger/Lens.hs+87−59
@@ -1,3 +1,4 @@
1+{-# LANGUAGE CPP #-}
12{-# LANGUAGE FlexibleContexts #-}
23{-# LANGUAGE FlexibleInstances #-}
34{-# LANGUAGE FunctionalDependencies #-}
@@ -5,7 +6,17 @@
56{-# LANGUAGE MultiParamTypeClasses #-}
67{-# LANGUAGE RankNTypes #-}
78{-# LANGUAGE TemplateHaskell #-}
9+{-# LANGUAGE TypeFamilies #-}
10+{-# LANGUAGE DataKinds #-}
811{-# LANGUAGE UndecidableInstances #-}
12+{-# OPTIONS_GHC -fno-warn-orphans #-}
13+#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.
920module Data.Swagger.Lens where
1021
1122import Control.Lens
@@ -15,84 +26,89 @@ import Data.Swagger.Internal
1526import Data.Swagger.Internal.Utils
1627import Data.Text (Text)
1728
18−-- =======================================================================
19−-- * TH derived lenses
29+-- * Classy lenses
2030
21−-- ** 'Swagger' lenses
2231makeFields ''Swagger
23−-- ** 'Host' lenses
2432makeFields ''Host
25−-- ** 'Info' lenses
2633makeFields ''Info
27−-- ** 'Contact' lenses
2834makeFields ''Contact
29−-- ** 'License' lenses
3035makeFields ''License
31−-- ** 'PathItem' lenses
32−makeFields ''PathItem
33−-- ** 'Tag' lenses
36+makeLensesWith swaggerFieldRules ''PathItem
3437makeFields ''Tag
35−-- ** 'Operation' lenses
3638makeFields ''Operation
37−-- ** 'Param' lenses
3839makeFields ''Param
39−-- ** 'ParamAnySchema' prisms
40−makePrisms ''ParamAnySchema
41−-- ** 'ParamOtherSchema' lenses
4240makeLensesWith swaggerFieldRules ''ParamOtherSchema
43−-- ** 'Header' lenses
4441makeFields ''Header
45−-- ** 'Schema' lenses
4642makeFields ''Schema
47−-- ** 'NamedSchema' lenses
4843makeFields ''NamedSchema
44+makeLensesWith swaggerFieldRules ''ParamSchema
45+makeFields ''Xml
46+makeLensesWith swaggerFieldRules ''Responses
47+makeFields ''Response
48+makeLensesWith swaggerFieldRules ''SecurityScheme
49+makeFields ''ApiKeyParams
50+makeFields ''OAuth2Params
51+makeFields ''ExternalDocs
52+
53+-- * Prisms
54+-- ** 'ParamAnySchema' prisms
55+makePrisms ''ParamAnySchema
56+-- ** 'SecuritySchemeType' prisms
57+makePrisms ''SecuritySchemeType
58+-- ** 'Referenced' prisms
59+makePrisms ''Referenced
4960
5061-- ** 'SwaggerItems' prisms
5162
52−_SwaggerItemsArray :: forall t. (t ~ Schema) => Review (SwaggerItems t) [Referenced Schema]
63+_SwaggerItemsArray :: Review (SwaggerItems 'SwaggerKindSchema) [Referenced Schema]
5364_SwaggerItemsArray
54− = prism (\x -> SwaggerItemsArray x) $ \x -> case x of
65+ = unto (\x -> SwaggerItemsArray x)
66+{- \x -> case x of
5567 SwaggerItemsPrimitive c p -> Left (SwaggerItemsPrimitive c p)
5668 SwaggerItemsObject o -> Left (SwaggerItemsObject o)
5769 SwaggerItemsArray a -> Right a
70+-}
5871
59−_SwaggerItemsObject :: forall t. (t ~ Schema) => Review (SwaggerItems t) (Referenced Schema)
72+_SwaggerItemsObject :: Review (SwaggerItems 'SwaggerKindSchema) (Referenced Schema)
6073_SwaggerItemsObject
61− = prism (\x -> SwaggerItemsObject x) $ \x -> case x of
74+ = unto (\x -> SwaggerItemsObject x)
75+{- \x -> case x of
6276 SwaggerItemsPrimitive c p -> Left (SwaggerItemsPrimitive c p)
6377 SwaggerItemsObject o -> Right o
6478 SwaggerItemsArray a -> Left (SwaggerItemsArray a)
79+-}
6580
6681_SwaggerItemsPrimitive :: forall t p f. (Profunctor p, Bifunctor p, Functor f) => Optic' p f (SwaggerItems t) (Maybe (CollectionFormat t), ParamSchema t)
6782_SwaggerItemsPrimitive = unto (\(c, p) -> SwaggerItemsPrimitive c p)
6883
69−-- ** 'ParamSchema' lenses
70−makeLensesWith swaggerFieldRules ''ParamSchema
71−-- ** 'Xml' lenses
72−makeFields ''Xml
73−-- ** 'Responses' lenses
74−makeLensesWith swaggerFieldRules ''Responses
75−-- ** 'Response' lenses
76−makeFields ''Response
77−-- ** 'SecurityScheme' lenses
78−makeLensesWith swaggerFieldRules ''SecurityScheme
79−-- ** 'SecuritySchemeType' prisms
80−makePrisms ''SecuritySchemeType
81−-- ** 'ApiKeyParams' lenses
82−makeFields ''ApiKeyParams
83−-- ** 'OAuth2Params' lenses
84−makeFields ''OAuth2Params
85−-- ** 'ExternalDocs' lenses
86−makeFields ''ExternalDocs
87−
8884-- =============================================================
8985-- More helpful instances for easier access to schema properties
9086
87+type instance Index Responses = HttpStatusCode
88+type instance Index Operation = HttpStatusCode
89+
90+type instance IxValue Responses = Referenced Response
91+type instance IxValue Operation = Referenced Response
92+
93+instance Ixed Responses where ix n = responses . ix n
94+instance At Responses where at n = responses . at n
95+
96+instance Ixed Operation where ix n = responses . ix n
97+instance At Operation where at n = responses . at n
98+
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+
91107-- HasType instances
92−instance HasType Header (SwaggerType Header) where type_ = paramSchema.type_
93−instance HasType Schema (SwaggerType Schema) where type_ = paramSchema.type_
94−instance HasType NamedSchema (SwaggerType Schema) where type_ = schema.paramSchema.type_
95−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_
96112
97113-- HasDefault instances
98114instance HasDefault Header (Maybe Value) where default_ = paramSchema.default_
@@ -101,58 +117,70 @@ instance HasDefault ParamOtherSchema (Maybe Value) where default_ = paramSchema.
101117
102118-- OVERLAPPABLE instances
103119
104−instance {-# OVERLAPPABLE #-} HasParamSchema s (ParamSchema t)
120+instance
121+#if __GLASGOW_HASKELL__ >= 710
122+ OVERLAPPABLE_
123+#endif
124+ HasParamSchema s (ParamSchema t)
105125 => HasFormat s (Maybe Format) where
106126 format = paramSchema.format
107127
108−instance {-# OVERLAPPABLE #-} HasParamSchema s (ParamSchema t)
128+instance
129+#if __GLASGOW_HASKELL__ >= 710
130+ OVERLAPPABLE_
131+#endif
132+ HasParamSchema s (ParamSchema t)
109133 => HasItems s (Maybe (SwaggerItems t)) where
110134 items = paramSchema.items
111135
112−instance {-# OVERLAPPABLE #-} HasParamSchema s (ParamSchema t)
136+instance
137+#if __GLASGOW_HASKELL__ >= 710
138+ OVERLAPPABLE_
139+#endif
140+ HasParamSchema s (ParamSchema t)
113141 => HasMaximum s (Maybe Scientific) where
114142 maximum_ = paramSchema.maximum_
115143
116−instance {-# OVERLAPPABLE #-} HasParamSchema s (ParamSchema t)
144+instance OVERLAPPABLE_ HasParamSchema s (ParamSchema t)
117145 => HasExclusiveMaximum s (Maybe Bool) where
118146 exclusiveMaximum = paramSchema.exclusiveMaximum
119147
120−instance {-# OVERLAPPABLE #-} HasParamSchema s (ParamSchema t)
148+instance OVERLAPPABLE_ HasParamSchema s (ParamSchema t)
121149 => HasMinimum s (Maybe Scientific) where
122150 minimum_ = paramSchema.minimum_
123151
124−instance {-# OVERLAPPABLE #-} HasParamSchema s (ParamSchema t)
152+instance OVERLAPPABLE_ HasParamSchema s (ParamSchema t)
125153 => HasExclusiveMinimum s (Maybe Bool) where
126154 exclusiveMinimum = paramSchema.exclusiveMinimum
127155
128−instance {-# OVERLAPPABLE #-} HasParamSchema s (ParamSchema t)
156+instance OVERLAPPABLE_ HasParamSchema s (ParamSchema t)
129157 => HasMaxLength s (Maybe Integer) where
130158 maxLength = paramSchema.maxLength
131159
132−instance {-# OVERLAPPABLE #-} HasParamSchema s (ParamSchema t)
160+instance OVERLAPPABLE_ HasParamSchema s (ParamSchema t)
133161 => HasMinLength s (Maybe Integer) where
134162 minLength = paramSchema.minLength
135163
136−instance {-# OVERLAPPABLE #-} HasParamSchema s (ParamSchema t)
164+instance OVERLAPPABLE_ HasParamSchema s (ParamSchema t)
137165 => HasPattern s (Maybe Text) where
138166 pattern = paramSchema.pattern
139167
140−instance {-# OVERLAPPABLE #-} HasParamSchema s (ParamSchema t)
168+instance OVERLAPPABLE_ HasParamSchema s (ParamSchema t)
141169 => HasMaxItems s (Maybe Integer) where
142170 maxItems = paramSchema.maxItems
143171
144−instance {-# OVERLAPPABLE #-} HasParamSchema s (ParamSchema t)
172+instance OVERLAPPABLE_ HasParamSchema s (ParamSchema t)
145173 => HasMinItems s (Maybe Integer) where
146174 minItems = paramSchema.minItems
147175
148−instance {-# OVERLAPPABLE #-} HasParamSchema s (ParamSchema t)
176+instance OVERLAPPABLE_ HasParamSchema s (ParamSchema t)
149177 => HasUniqueItems s (Maybe Bool) where
150178 uniqueItems = paramSchema.uniqueItems
151179
152−instance {-# OVERLAPPABLE #-} HasParamSchema s (ParamSchema t)
180+instance OVERLAPPABLE_ HasParamSchema s (ParamSchema t)
153181 => HasEnum s (Maybe [Value]) where
154182 enum_ = paramSchema.enum_
155183
156−instance {-# OVERLAPPABLE #-} HasParamSchema s (ParamSchema t)
184+instance OVERLAPPABLE_ HasParamSchema s (ParamSchema t)
157185 => HasMultipleOf s (Maybe Scientific) where
158186 multipleOf = paramSchema.multipleOf
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/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.yaml+6−2
@@ -1,5 +1,9 @@
1−flags: {}
1+resolver: lts-14.3
22packages:
33- '.'
44extra-deps:
5−resolver: lts-3.12
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+107−34
@@ -1,79 +1,152 @@
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
18−cabal-version: >=1.10
25+ , include/overlapping-compat.h
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
1936
2037library
2138 hs-source-dirs: src
39+ include-dirs: include
2240 exposed-modules:
2341 Data.Swagger
2442 Data.Swagger.Declare
2543 Data.Swagger.Lens
44+ Data.Swagger.Operation
45+ Data.Swagger.Optics
2646 Data.Swagger.ParamSchema
2747 Data.Swagger.Schema
48+ Data.Swagger.Schema.Generator
49+ Data.Swagger.Schema.Validation
2850 Data.Swagger.SchemaOptions
2951
3052 -- internal modules
3153 Data.Swagger.Internal
3254 Data.Swagger.Internal.Schema
55+ Data.Swagger.Internal.Schema.Validation
3356 Data.Swagger.Internal.ParamSchema
3457 Data.Swagger.Internal.Utils
35− build-depends: base == 4.*
36− , aeson
37− , containers
38− , hashable
39− , http-media
40− , mtl
41− , network
42− , text
43− , template-haskell
44− , time
45− , unordered-containers
46− , lens
47− , scientific
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+
4896 default-language: Haskell2010
4997
5098test-suite spec
5199 type: exitcode-stdio-1.0
52100 hs-source-dirs: test
53101 main-is: Spec.hs
54− build-depends: base == 4.*
55− , swagger2
56− , hspec
57− , HUnit
58− , QuickCheck
59− , text
60− , aeson
61− , aeson-qq
62− , containers
63− , unordered-containers
64− , vector
65− , 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+
66134 other-modules:
67135 SpecCommon
68136 Data.SwaggerSpec
137+ Data.Swagger.CommonTestTypes
138+ Data.Swagger.ParamSchemaSpec
69139 Data.Swagger.SchemaSpec
140+ Data.Swagger.Schema.ValidationSpec
141+ Data.Swagger.Schema.GeneratorSpec
70142 default-language: Haskell2010
71143
72−test-suite doctest
73− 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
74147 default-language: Haskell2010
75148 hs-source-dirs: test
76− main-is: DocTest.hs
149+ main-is: doctests.hs
77150 type: exitcode-stdio-1.0
78151
79152source-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−82
@@ -1,24 +1,29 @@
11{-# LANGUAGE DeriveGeneric #-}
2−{-# LANGUAGE DeriveAnyClass #-}
2+{-# LANGUAGE DataKinds #-}
33{-# LANGUAGE ScopedTypeVariables #-}
44{-# LANGUAGE TemplateHaskell #-}
55{-# LANGUAGE QuasiQuotes #-}
6+{-# LANGUAGE OverloadedStrings #-}
67module Data.Swagger.ParamSchemaSpec where
78
89import Data.Aeson
9−import Data.Aeson.QQ
10+import Data.Aeson.QQ.Simple
1011import Data.Char
1112import Data.Proxy
12−import Data.Set (Set)
1313import GHC.Generics
1414
1515import Data.Swagger
16+import Data.Swagger.Internal (SwaggerKind(..))
1617
18+import Data.Swagger.CommonTestTypes
1719import SpecCommon
1820import Test.Hspec
21+import Data.Time.LocalTime
22+
23+import qualified Data.HashMap.Strict as HM
1924
2025checkToParamSchema :: ToParamSchema a => Proxy a -> Value -> Spec
21−checkToParamSchema proxy js = (toParamSchema proxy :: ParamSchema Param) <=> js
26+checkToParamSchema proxy js = (toParamSchema proxy :: ParamSchema ('SwaggerKindNormal Param)) <=> js
2227
2328spec :: Spec
2429spec = do
@@ -29,84 +34,7 @@ spec = do
2934 context "Unary records" $ do
3035 context "Email (unary record)" $ checkToParamSchema (Proxy :: Proxy Email) emailSchemaJSON
3136 context "UserId (non-record newtype)" $ checkToParamSchema (Proxy :: Proxy UserId) userIdSchemaJSON
37+ context "TimeOfDay" $ checkToParamSchema (Proxy :: Proxy Data.Time.LocalTime.TimeOfDay) timeOfDayParamSchemaJSON
3238
3339main :: IO ()
3440main = hspec spec
35−
36−-- ========================================================================
37−-- Unit type
38−-- ========================================================================
39−
40−data Unit = Unit deriving (Generic, ToParamSchema)
41−
42−unitSchemaJSON :: Value
43−unitSchemaJSON = [aesonQQ|
44−{
45− "type": "string",
46− "enum": ["Unit"]
47−}
48−|]
49−
50−-- ========================================================================
51−-- Color (enum)
52−-- ========================================================================
53−data Color
54− = Red
55− | Green
56− | Blue
57− deriving (Generic, ToParamSchema)
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, ToParamSchema)
91−
92−emailSchemaJSON :: Value
93−emailSchemaJSON = [aesonQQ|
94−{
95− "type": "string"
96−}
97−|]
98−
99−-- ========================================================================
100−-- UserId (non-record newtype)
101−-- ========================================================================
102−
103−newtype UserId = UserId Integer
104− deriving (Generic, ToParamSchema)
105−
106−userIdSchemaJSON :: Value
107−userIdSchemaJSON = [aesonQQ|
108−{
109− "type": "integer"
110−}
111−|]
112−
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+32−501
@@ -1,27 +1,29 @@
11{-# LANGUAGE DeriveGeneric #-}
2−{-# LANGUAGE DeriveAnyClass #-}
32{-# LANGUAGE ScopedTypeVariables #-}
43{-# LANGUAGE TemplateHaskell #-}
54{-# LANGUAGE QuasiQuotes #-}
65module Data.Swagger.SchemaSpec where
76
8−import Data.Aeson
9−import Data.Aeson.QQ
10−import Data.Char
11−import qualified Data.HashMap.Strict as HashMap
7+import Prelude ()
8+import Prelude.Compat
9+
10+import Control.Lens ((^.))
11+import Data.Aeson (Value)
12+import qualified Data.HashMap.Strict.InsOrd as InsOrdHashMap
1213import Data.Proxy
1314import Data.Set (Set)
14−import qualified Data.Set as Set
15−import Data.Text (Text)
1615import qualified Data.Text as Text
17−import GHC.Generics
1816
1917import Data.Swagger
2018import Data.Swagger.Declare
2119
20+import Data.Swagger.CommonTestTypes
2221import SpecCommon
2322import Test.Hspec
2423
24+import qualified Data.HashMap.Strict as HM
25+import Data.Time.LocalTime
26+
2527checkToSchema :: ToSchema a => Proxy a -> Value -> Spec
2628checkToSchema proxy js = toSchema proxy <=> js
2729
@@ -33,22 +35,29 @@ checkSchemaName sname proxy =
3335checkDefs :: ToSchema a => Proxy a -> [String] -> Spec
3436checkDefs proxy names =
3537 it ("uses these definitions " ++ show names) $
36− Set.fromList (HashMap.keys defs) `shouldBe` Set.fromList (map Text.pack names)
38+ InsOrdHashMap.keys defs `shouldBe` map Text.pack names
3739 where
3840 defs = execDeclare (declareNamedSchema proxy) mempty
3941
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+
4049checkInlinedSchema :: ToSchema a => Proxy a -> Value -> Spec
4150checkInlinedSchema proxy js = toInlinedSchema proxy <=> js
4251
4352checkInlinedSchemas :: ToSchema a => [String] -> Proxy a -> Value -> Spec
44−checkInlinedSchemas names proxy js = inlineSchemas (map Text.pack names) defs schema <=> js
53+checkInlinedSchemas names proxy js = inlineSchemas (map Text.pack names) defs s <=> js
4554 where
46− (defs, schema) = runDeclare (declareSchema proxy) mempty
55+ (defs, s) = runDeclare (declareSchema proxy) mempty
4756
4857checkInlinedRecSchema :: ToSchema a => Proxy a -> Value -> Spec
49−checkInlinedRecSchema proxy js = inlineNonRecursiveSchemas defs schema <=> js
58+checkInlinedRecSchema proxy js = inlineNonRecursiveSchemas defs s <=> js
5059 where
51− (defs, schema) = runDeclare (declareSchema proxy) mempty
60+ (defs, s) = runDeclare (declareSchema proxy) mempty
5261
5362spec :: Spec
5463spec = do
@@ -57,6 +66,9 @@ spec = do
5766 context "Person" $ checkToSchema (Proxy :: Proxy Person) personSchemaJSON
5867 context "ISPair" $ checkToSchema (Proxy :: Proxy ISPair) ispairSchemaJSON
5968 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
6072 context "Color (bounded enum)" $ checkToSchema (Proxy :: Proxy Color) colorSchemaJSON
6173 context "Shade (paramSchemaToNamedSchema)" $ checkToSchema (Proxy :: Proxy Shade) shadeSchemaJSON
6274 context "Paint (record with bounded enum field)" $ checkToSchema (Proxy :: Proxy Paint) paintSchemaJSON
@@ -65,8 +77,10 @@ spec = do
6577 context "Email (unwrapUnaryRecords)" $ checkToSchema (Proxy :: Proxy Email) emailSchemaJSON
6678 context "UserId (non-record newtype)" $ checkToSchema (Proxy :: Proxy UserId) userIdSchemaJSON
6779 context "Player (unary record)" $ checkToSchema (Proxy :: Proxy Player) playerSchemaJSON
80+ context "SingleMaybeField (unary record with Maybe)" $ checkToSchema (Proxy :: Proxy SingleMaybeField) singleMaybeFieldSchemaJSON
6881 context "Players (inlining schema)" $ checkToSchema (Proxy :: Proxy Players) playersSchemaJSON
6982 context "MyRoseTree (datatypeNameModifier)" $ checkToSchema (Proxy :: Proxy MyRoseTree) myRoseTreeSchemaJSON
83+ context "MyRoseTree' (datatypeNameModifier)" $ checkToSchema (Proxy :: Proxy MyRoseTree') myRoseTreeSchemaJSON'
7084 context "Sum types" $ do
7185 context "Status (sum of unary constructors)" $ checkToSchema (Proxy :: Proxy Status) statusSchemaJSON
7286 context "Character (ref and record sum)" $ checkToSchema (Proxy :: Proxy Character) characterSchemaJSON
@@ -82,6 +96,7 @@ spec = do
8296 context "Light" $ checkDefs (Proxy :: Proxy Light) ["Color"]
8397 context "Character" $ checkDefs (Proxy :: Proxy Character) ["Player", "Point"]
8498 context "MyRoseTree" $ checkDefs (Proxy :: Proxy MyRoseTree) ["RoseTree"]
99+ context "MyRoseTree'" $ checkDefs (Proxy :: Proxy MyRoseTree') ["myrosetree'"]
85100 context "[Set (Unit, Maybe Color)]" $ checkDefs (Proxy :: Proxy [Set (Unit, Maybe Color)]) ["Unit", "Color"]
86101 context "ResourceId" $ checkDefs (Proxy :: Proxy ResourceId) []
87102 describe "Inlining Schemas" $ do
@@ -90,494 +105,10 @@ spec = do
90105 context "Character (inlining only Player)" $ checkInlinedSchemas ["Player"] (Proxy :: Proxy Character) characterInlinedPlayerSchemaJSON
91106 context "Light" $ checkInlinedSchema (Proxy :: Proxy Light) lightInlinedSchemaJSON
92107 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
93112
94113main :: IO ()
95114main = hspec spec
96−
97−-- ========================================================================
98−-- Person (simple record with optional fields)
99−-- ========================================================================
100−data Person = Person
101− { name :: String
102− , phone :: Integer
103− , email :: Maybe String
104− } deriving (Generic, ToSchema)
105−
106−personSchemaJSON :: Value
107−personSchemaJSON = [aesonQQ|
108−{
109− "type": "object",
110− "properties":
111− {
112− "name": { "type": "string" },
113− "phone": { "type": "integer" },
114− "email": { "type": "string" }
115− },
116− "required": ["name", "phone"]
117−}
118−|]
119−
120−-- ========================================================================
121−-- ISPair (non-record product data type)
122−-- ========================================================================
123−data ISPair = ISPair Integer String
124− deriving (Generic, ToSchema)
125−
126−ispairSchemaJSON :: Value
127−ispairSchemaJSON = [aesonQQ|
128−{
129− "type": "array",
130− "items":
131− [
132− { "type": "integer" },
133− { "type": "string" }
134− ]
135−}
136−|]
137−
138−-- ========================================================================
139−-- Point (record data type with custom fieldLabelModifier)
140−-- ========================================================================
141−data Point = Point
142− { pointX :: Double
143− , pointY :: Double
144− } deriving (Generic)
145−
146−instance ToSchema Point where
147− declareNamedSchema = genericDeclareNamedSchema defaultSchemaOptions
148− { fieldLabelModifier = map toLower . drop (length "point") }
149−
150−pointSchemaJSON :: Value
151−pointSchemaJSON = [aesonQQ|
152−{
153− "type": "object",
154− "properties":
155− {
156− "x": { "type": "number", "format": "double" },
157− "y": { "type": "number", "format": "double" }
158− },
159− "required": ["x", "y"]
160−}
161−|]
162−
163−
164−-- ========================================================================
165−-- Color (enum)
166−-- ========================================================================
167−data Color
168− = Red
169− | Green
170− | Blue
171− deriving (Generic, ToSchema)
172−
173−colorSchemaJSON :: Value
174−colorSchemaJSON = [aesonQQ|
175−{
176− "type": "string",
177− "enum": ["Red", "Green", "Blue"]
178−}
179−|]
180−
181−-- ========================================================================
182−-- Shade (paramSchemaToNamedSchema)
183−-- ========================================================================
184−
185−data Shade = Dim | Bright deriving (Generic, ToParamSchema)
186−
187−instance ToSchema Shade where declareNamedSchema = pure . paramSchemaToNamedSchema defaultSchemaOptions
188−
189−shadeSchemaJSON :: Value
190−shadeSchemaJSON = [aesonQQ|
191−{
192− "type": "string",
193− "enum": ["Dim", "Bright"]
194−}
195−|]
196−
197−-- ========================================================================
198−-- Paint (record with bounded enum property)
199−-- ========================================================================
200−
201−newtype Paint = Paint { color :: Color }
202− deriving (Generic, ToSchema)
203−
204−paintSchemaJSON :: Value
205−paintSchemaJSON = [aesonQQ|
206−{
207− "type": "object",
208− "properties":
209− {
210− "color":
211− {
212− "$ref": "#/definitions/Color"
213− }
214− },
215− "required": ["color"]
216−}
217−|]
218−
219−paintInlinedSchemaJSON :: Value
220−paintInlinedSchemaJSON = [aesonQQ|
221−{
222− "type": "object",
223− "properties":
224− {
225− "color":
226− {
227− "type": "string",
228− "enum": ["Red", "Green", "Blue"]
229− }
230− },
231− "required": ["color"]
232−}
233−|]
234−
235−-- ========================================================================
236−-- Email (newtype with unwrapUnaryRecords set to True)
237−-- ========================================================================
238−
239−newtype Email = Email { getEmail :: String }
240− deriving (Generic)
241−
242−instance ToSchema Email where
243− declareNamedSchema = genericDeclareNamedSchema defaultSchemaOptions
244− { unwrapUnaryRecords = True }
245−
246−emailSchemaJSON :: Value
247−emailSchemaJSON = [aesonQQ|
248−{
249− "type": "string"
250−}
251−|]
252−
253−-- ========================================================================
254−-- UserId (non-record newtype)
255−-- ========================================================================
256−
257−newtype UserId = UserId Integer
258− deriving (Eq, Ord, Generic, ToSchema)
259−
260−userIdSchemaJSON :: Value
261−userIdSchemaJSON = [aesonQQ|
262−{
263− "type": "integer"
264−}
265−|]
266−
267−-- ========================================================================
268−-- UserGroup (set newtype)
269−-- ========================================================================
270−
271−newtype UserGroup = UserGroup (Set UserId)
272− deriving (Generic, ToSchema)
273−
274−userGroupSchemaJSON :: Value
275−userGroupSchemaJSON = [aesonQQ|
276−{
277− "type": "array",
278− "items": { "$ref": "#/definitions/UserId" },
279− "uniqueItems": true
280−}
281−|]
282−
283−-- ========================================================================
284−-- Player (record newtype)
285−-- ========================================================================
286−
287−newtype Player = Player
288− { position :: Point
289− } deriving (Generic, ToSchema)
290−
291−playerSchemaJSON :: Value
292−playerSchemaJSON = [aesonQQ|
293−{
294− "type": "object",
295− "properties":
296− {
297− "position":
298− {
299− "$ref": "#/definitions/Point"
300− }
301− },
302− "required": ["position"]
303−}
304−|]
305−
306−-- ========================================================================
307−-- MyRoseTree (custom datatypeNameModifier)
308−-- ========================================================================
309−
310−data MyRoseTree = MyRoseTree
311− { root :: String
312− , trees :: [MyRoseTree]
313− } deriving (Generic)
314−
315−instance ToSchema MyRoseTree where
316− declareNamedSchema = genericDeclareNamedSchema defaultSchemaOptions
317− { datatypeNameModifier = drop (length "My") }
318−
319−myRoseTreeSchemaJSON :: Value
320−myRoseTreeSchemaJSON = [aesonQQ|
321−{
322− "type": "object",
323− "properties":
324− {
325− "root": { "type": "string" },
326− "trees":
327− {
328− "type": "array",
329− "items":
330− {
331− "$ref": "#/definitions/RoseTree"
332− }
333− }
334− },
335− "required": ["root", "trees"]
336−}
337−|]
338−
339−-- ========================================================================
340−-- Inlined (newtype for inlining schemas)
341−-- ========================================================================
342−
343−newtype Inlined a = Inlined { getInlined :: a }
344−
345−instance ToSchema a => ToSchema (Inlined a) where
346− declareNamedSchema _ = unname <$> declareNamedSchema (Proxy :: Proxy a)
347− where
348− unname (NamedSchema _ schema) = NamedSchema Nothing schema
349−
350−newtype Players = Players [Inlined Player]
351− deriving (Generic, ToSchema)
352−
353−playersSchemaJSON :: Value
354−playersSchemaJSON = [aesonQQ|
355−{
356− "type": "array",
357− "items":
358− {
359− "type": "object",
360− "properties":
361− {
362− "position":
363− {
364− "$ref": "#/definitions/Point"
365− }
366− },
367− "required": ["position"]
368− }
369−}
370−|]
371−
372−-- ========================================================================
373−-- Status (sum type with unary constructors)
374−-- ========================================================================
375−
376−data Status
377− = StatusOk String
378− | StatusError String
379− deriving (Generic)
380−
381−instance ToSchema Status where
382− declareNamedSchema = genericDeclareNamedSchema defaultSchemaOptions
383− { constructorTagModifier = map toLower . drop (length "Status") }
384−
385−statusSchemaJSON :: Value
386−statusSchemaJSON = [aesonQQ|
387−{
388− "type": "object",
389− "properties":
390− {
391− "ok": { "type": "string" },
392− "error": { "type": "string" }
393− },
394− "maxProperties": 1,
395− "minProperties": 1
396−}
397−|]
398−
399−-- ========================================================================
400−-- Unit type
401−-- ========================================================================
402−
403−data Unit = Unit deriving (Generic, ToSchema)
404−
405−unitSchemaJSON :: Value
406−unitSchemaJSON = [aesonQQ|
407−{
408− "type": "string",
409− "enum": ["Unit"]
410−}
411−|]
412−
413−
414−-- ========================================================================
415−-- Character (sum type with ref and record in alternative)
416−-- ========================================================================
417−
418−data Character
419− = PC Player
420− | NPC { npcName :: String, npcPosition :: Point }
421− deriving (Generic, ToSchema)
422−
423−characterSchemaJSON :: Value
424−characterSchemaJSON = [aesonQQ|
425−{
426− "type": "object",
427− "properties":
428− {
429− "PC": { "$ref": "#/definitions/Player" },
430− "NPC":
431− {
432− "type": "object",
433− "properties":
434− {
435− "npcName": { "type": "string" },
436− "npcPosition": { "$ref": "#/definitions/Point" }
437− },
438− "required": ["npcName", "npcPosition"]
439− }
440− },
441− "maxProperties": 1,
442− "minProperties": 1
443−}
444−|]
445−
446−characterInlinedSchemaJSON :: Value
447−characterInlinedSchemaJSON = [aesonQQ|
448−{
449− "type": "object",
450− "properties":
451− {
452− "PC":
453− {
454− "type": "object",
455− "properties":
456− {
457− "position":
458− {
459− "type": "object",
460− "properties":
461− {
462− "x": { "type": "number", "format": "double" },
463− "y": { "type": "number", "format": "double" }
464− },
465− "required": ["x", "y"]
466− }
467− },
468− "required": ["position"]
469− },
470− "NPC":
471− {
472− "type": "object",
473− "properties":
474− {
475− "npcName": { "type": "string" },
476− "npcPosition":
477− {
478− "type": "object",
479− "properties":
480− {
481− "x": { "type": "number", "format": "double" },
482− "y": { "type": "number", "format": "double" }
483− },
484− "required": ["x", "y"]
485− }
486− },
487− "required": ["npcName", "npcPosition"]
488− }
489− },
490− "maxProperties": 1,
491− "minProperties": 1
492−}
493−|]
494−
495−characterInlinedPlayerSchemaJSON :: Value
496−characterInlinedPlayerSchemaJSON = [aesonQQ|
497−{
498− "type": "object",
499− "properties":
500− {
501− "PC":
502− {
503− "type": "object",
504− "properties":
505− {
506− "position":
507− {
508− "$ref": "#/definitions/Point"
509− }
510− },
511− "required": ["position"]
512− },
513− "NPC":
514− {
515− "type": "object",
516− "properties":
517− {
518− "npcName": { "type": "string" },
519− "npcPosition": { "$ref": "#/definitions/Point" }
520− },
521− "required": ["npcName", "npcPosition"]
522− }
523− },
524− "maxProperties": 1,
525− "minProperties": 1
526−}
527−|]
528−
529−-- ========================================================================
530−-- Light (sum type with unwrapUnaryRecords)
531−-- ========================================================================
532−
533−data Light
534− = LightFreq Double
535− | LightColor Color
536− | LightWaveLength { waveLength :: Double }
537− deriving (Generic)
538−
539−instance ToSchema Light where
540− declareNamedSchema = genericDeclareNamedSchema defaultSchemaOptions
541− { unwrapUnaryRecords = True }
542−
543−lightSchemaJSON :: Value
544−lightSchemaJSON = [aesonQQ|
545−{
546− "type": "object",
547− "properties":
548− {
549− "LightFreq": { "type": "number", "format": "double" },
550− "LightColor": { "$ref": "#/definitions/Color" },
551− "LightWaveLength": { "type": "number", "format": "double" }
552− },
553− "maxProperties": 1,
554− "minProperties": 1
555−}
556−|]
557−
558−lightInlinedSchemaJSON :: Value
559−lightInlinedSchemaJSON = [aesonQQ|
560−{
561− "type": "object",
562− "properties":
563− {
564− "LightFreq": { "type": "number", "format": "double" },
565− "LightColor":
566− {
567− "type": "string",
568− "enum": ["Red", "Green", "Blue"]
569− },
570− "LightWaveLength": { "type": "number", "format": "double" }
571− },
572− "maxProperties": 1,
573− "minProperties": 1
574−}
575−|]
576−
577−-- ========================================================================
578−-- ResourceId (series of newtypes)
579−-- ========================================================================
580−
581−newtype Id = Id String deriving (Generic, ToSchema)
582−
583−newtype ResourceId = ResourceId Id deriving (Generic, ToSchema)
test/Data/SwaggerSpec.hs+516−433
@@ -4,19 +4,31 @@
44{-# LANGUAGE QuasiQuotes #-}
55module Data.SwaggerSpec where
66
7+import Prelude ()
8+import Prelude.Compat
9+
710import Control.Lens
811
912import Data.Aeson
10−import Data.Aeson.QQ
13+import Data.Aeson.QQ.Simple
1114import Data.HashMap.Strict (HashMap)
15+import qualified Data.HashSet.InsOrd as InsOrdHS
1216import Data.Text (Text)
1317
1418import Data.Swagger
1519import SpecCommon
16−import Test.Hspec
20+import Test.Hspec hiding (example)
1721
1822spec :: Spec
1923spec = 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
2032 describe "License Object" $ licenseExample <=> licenseExampleJSON
2133 describe "Contact Object" $ contactExample <=> contactExampleJSON
2234 describe "Info Object" $ infoExample <=> infoExampleJSON
@@ -25,11 +37,14 @@ spec = do
2537 context "Primitive Sample" $ schemaPrimitiveExample <=> schemaPrimitiveExampleJSON
2638 context "Simple Model" $ schemaSimpleModelExample <=> schemaSimpleModelExampleJSON
2739 context "Model with Map/Dictionary Properties" $ schemaModelDictExample <=> schemaModelDictExampleJSON
40+ context "Model with Arbitrary Properties" $ schemaAdditionalExample <=> schemaAdditionalExampleJSON
2841 context "Model with Example" $ schemaWithExampleExample <=> schemaWithExampleExampleJSON
2942 describe "Definitions Object" $ definitionsExample <=> definitionsExampleJSON
3043 describe "Parameters Definition Object" $ paramsDefinitionExample <=> paramsDefinitionExampleJSON
3144 describe "Responses Definition Object" $ responsesDefinitionExample <=> responsesDefinitionExampleJSON
3245 describe "Security Definitions Object" $ securityDefinitionsExample <=> securityDefinitionsExampleJSON
46+ describe "OAuth2 Security Definitions with merged Scope" $ oAuth2SecurityDefinitionsExample <=> oAuth2SecurityDefinitionsExampleJSON
47+ describe "Composition Schema Example" $ compositionSchemaExample <=> compositionSchemaExampleJSON
3348 describe "Swagger Object" $ do
3449 context "Todo Example" $ swaggerExample <=> swaggerExampleJSON
3550 context "PetStore Example" $
@@ -44,13 +59,13 @@ main = hspec spec
4459-- =======================================================================
4560
4661infoExample :: Info
47−infoExample = Info
48− { _infoTitle = "Swagger Sample App"
49− , _infoDescription = Just "This is a sample server Petstore server."
50− , _infoTermsOfService = Just "http://swagger.io/terms/"
51− , _infoContact = Just contactExample
52− , _infoLicense = Just licenseExample
53− , _infoVersion = "1.0.1" }
62+infoExample = mempty
63+ & title .~ "Swagger Sample App"
64+ & description ?~ "This is a sample server Petstore server."
65+ & termsOfService ?~ "http://swagger.io/terms/"
66+ & contact ?~ contactExample
67+ & license ?~ licenseExample
68+ & version .~ "1.0.1"
5469
5570infoExampleJSON :: Value
5671infoExampleJSON = [aesonQQ|
@@ -76,10 +91,10 @@ infoExampleJSON = [aesonQQ|
7691-- =======================================================================
7792
7893contactExample :: Contact
79−contactExample = Contact
80− { _contactName = Just "API Support"
81− , _contactUrl = Just (URL "http://www.swagger.io/support")
82− , _contactEmail = Just "support@swagger.io" }
94+contactExample = mempty
95+ & name ?~ "API Support"
96+ & url ?~ URL "http://www.swagger.io/support"
97+ & email ?~ "support@swagger.io"
8398
8499contactExampleJSON :: Value
85100contactExampleJSON = [aesonQQ|
@@ -95,9 +110,8 @@ contactExampleJSON = [aesonQQ|
95110-- =======================================================================
96111
97112licenseExample :: License
98−licenseExample = License
99− { _licenseName = "Apache 2.0"
100− , _licenseUrl = 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"
101115
102116licenseExampleJSON :: Value
103117licenseExampleJSON = [aesonQQ|
@@ -114,46 +128,38 @@ licenseExampleJSON = [aesonQQ|
114128
115129operationExample :: Operation
116130operationExample = mempty
117− { _operationTags = ["pet"]
118− , _operationSummary = Just "Updates a pet in the store with form data"
119− , _operationDescription = Just ""
120− , _operationOperationId = Just "updatePetWithForm"
121− , _operationConsumes = Just (MimeList ["application/x-www-form-urlencoded"])
122− , _operationProduces = Just (MimeList ["application/json", "application/xml"])
123− , _operationParameters = params
124− , _operationResponses = responses
125− , _operationSecurity = security
126− }
127− where
128− security = [SecurityRequirement [("petstore_auth", ["write:pets", "read:pets"])]]
129−
130− responses = mempty
131− { _responsesResponses =
132− [ (200, Inline mempty { _responseDescription = "Pet updated." })
133− , (405, Inline mempty { _responseDescription = "Invalid input" }) ] }
134−
135− params = map Inline
136− [ Param
137− { _paramName = "petId"
138− , _paramDescription = Just "ID of pet that needs to be updated"
139− , _paramRequired = Just True
140− , _paramSchema = ParamOther (stringSchema ParamPath) }
141− , Param
142− { _paramName = "name"
143− , _paramDescription = Just "Updated name of the pet"
144− , _paramRequired = Just False
145− , _paramSchema = ParamOther (stringSchema ParamFormData) }
146− , Param
147− { _paramName = "status"
148− , _paramDescription = Just "Updated status of the pet"
149− , _paramRequired = Just False
150− , _paramSchema = ParamOther (stringSchema ParamFormData) }
131+ & tags .~ InsOrdHS.fromList ["pet"]
132+ & summary ?~ "Updates a pet in the store with form data"
133+ & description ?~ ""
134+ & operationId ?~ "updatePetWithForm"
135+ & consumes ?~ MimeList ["application/x-www-form-urlencoded"]
136+ & produces ?~ MimeList ["application/json", "application/xml"]
137+ & parameters .~ map Inline
138+ [ mempty
139+ & name .~ "petId"
140+ & description ?~ "ID of pet that needs to be updated"
141+ & required ?~ True
142+ & schema .~ ParamOther (stringSchema ParamPath)
143+ , mempty
144+ & name .~ "name"
145+ & description ?~ "Updated name of the pet"
146+ & required ?~ False
147+ & schema .~ ParamOther (stringSchema ParamFormData)
148+ , mempty
149+ & name .~ "status"
150+ & description ?~ "Updated status of the pet"
151+ & required ?~ False
152+ & schema .~ ParamOther (stringSchema ParamFormData)
151153 ]
152154
155+ & at 200 ?~ "Pet updated."
156+ & at 405 ?~ "Invalid input"
157+ & security .~ [SecurityRequirement [("petstore_auth", ["write:pets", "read:pets"])]]
158+ where
153159 stringSchema :: ParamLocation -> ParamOtherSchema
154160 stringSchema loc = mempty
155161 & in_ .~ loc
156− & type_ .~ SwaggerString
162+ & type_ ?~ SwaggerString
157163
158164operationExampleJSON :: Value
159165operationExampleJSON = [aesonQQ|
@@ -219,7 +225,7 @@ operationExampleJSON = [aesonQQ|
219225
220226schemaPrimitiveExample :: Schema
221227schemaPrimitiveExample = mempty
222− & type_ .~ SwaggerString
228+ & type_ ?~ SwaggerString
223229 & format ?~ "email"
224230
225231schemaPrimitiveExampleJSON :: Value
@@ -232,14 +238,14 @@ schemaPrimitiveExampleJSON = [aesonQQ|
232238
233239schemaSimpleModelExample :: Schema
234240schemaSimpleModelExample = mempty
235− & type_ .~ SwaggerObject
241+ & type_ ?~ SwaggerObject
236242 & required .~ [ "name" ]
237243 & properties .~
238− [ ("name", Inline (mempty & type_ .~ SwaggerString))
244+ [ ("name", Inline (mempty & type_ ?~ SwaggerString))
239245 , ("address", Ref (Reference "Address"))
240246 , ("age", Inline $ mempty
241247 & minimum_ ?~ 0
242− & type_ .~ SwaggerInteger
248+ & type_ ?~ SwaggerInteger
243249 & format ?~ "int32" ) ]
244250
245251schemaSimpleModelExampleJSON :: Value
@@ -267,8 +273,8 @@ schemaSimpleModelExampleJSON = [aesonQQ|
267273
268274schemaModelDictExample :: Schema
269275schemaModelDictExample = mempty
270− & type_ .~ SwaggerObject
271− & additionalProperties ?~ (mempty & type_ .~ SwaggerString)
276+ & type_ ?~ SwaggerObject
277+ & additionalProperties ?~ AdditionalPropertiesSchema (Inline (mempty & type_ ?~ SwaggerString))
272278
273279schemaModelDictExampleJSON :: Value
274280schemaModelDictExampleJSON = [aesonQQ|
@@ -280,20 +286,35 @@ schemaModelDictExampleJSON = [aesonQQ|
280286}
281287|]
282288
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+
283302schemaWithExampleExample :: Schema
284−schemaWithExampleExample = (mempty & type_ .~ SwaggerObject)
285− { _schemaProperties =
303+schemaWithExampleExample = mempty
304+ & type_ ?~ SwaggerObject
305+ & properties .~
286306 [ ("id", Inline $ mempty
287− & type_ .~ SwaggerInteger
307+ & type_ ?~ SwaggerInteger
288308 & format ?~ "int64" )
289− , ("name", Inline (mempty & type_ .~ SwaggerString)) ]
290− , _schemaRequired = [ "name" ]
291− , _schemaExample = Just [aesonQQ|
292− {
293− "name": "Puma",
294− "id": 1
295− }
296− |] }
309+ , ("name", Inline $ mempty
310+ & type_ ?~ SwaggerString) ]
311+ & required .~ [ "name" ]
312+ & example ?~ [aesonQQ|
313+ {
314+ "name": "Puma",
315+ "id": 1
316+ }
317+ |]
297318
298319schemaWithExampleExampleJSON :: Value
299320schemaWithExampleExampleJSON = [aesonQQ|
@@ -325,19 +346,19 @@ schemaWithExampleExampleJSON = [aesonQQ|
325346definitionsExample :: HashMap Text Schema
326347definitionsExample =
327348 [ ("Category", mempty
328− & type_ .~ SwaggerObject
349+ & type_ ?~ SwaggerObject
329350 & properties .~
330351 [ ("id", Inline $ mempty
331− & type_ .~ SwaggerInteger
352+ & type_ ?~ SwaggerInteger
332353 & format ?~ "int64")
333− , ("name", Inline (mempty & type_ .~ SwaggerString)) ] )
354+ , ("name", Inline (mempty & type_ ?~ SwaggerString)) ] )
334355 , ("Tag", mempty
335− & type_ .~ SwaggerObject
356+ & type_ ?~ SwaggerObject
336357 & properties .~
337358 [ ("id", Inline $ mempty
338− & type_ .~ SwaggerInteger
359+ & type_ ?~ SwaggerInteger
339360 & format ?~ "int64")
340− , ("name", Inline (mempty & type_ .~ SwaggerString)) ] ) ]
361+ , ("name", Inline (mempty & type_ ?~ SwaggerString)) ] ) ]
341362
342363definitionsExampleJSON :: Value
343364definitionsExampleJSON = [aesonQQ|
@@ -376,21 +397,21 @@ definitionsExampleJSON = [aesonQQ|
376397paramsDefinitionExample :: HashMap Text Param
377398paramsDefinitionExample =
378399 [ ("skipParam", mempty
379− { _paramName = "skip"
380− , _paramDescription = Just "number of items to skip"
381− , _paramRequired = Just True
382− , _paramSchema = ParamOther $ mempty
400+ & name .~ "skip"
401+ & description ?~ "number of items to skip"
402+ & required ?~ True
403+ & schema .~ ParamOther (mempty
383404 & in_ .~ ParamQuery
384− & type_ .~ SwaggerInteger
385− & format ?~ "int32" })
405+ & type_ ?~ SwaggerInteger
406+ & format ?~ "int32" ))
386407 , ("limitParam", mempty
387− { _paramName = "limit"
388− , _paramDescription = Just "max records to return"
389− , _paramRequired = Just True
390− , _paramSchema = ParamOther $ mempty
408+ & name .~ "limit"
409+ & description ?~ "max records to return"
410+ & required ?~ True
411+ & schema .~ ParamOther (mempty
391412 & in_ .~ ParamQuery
392− & type_ .~ SwaggerInteger
393− & format ?~ "int32" }) ]
413+ & type_ ?~ SwaggerInteger
414+ & format ?~ "int32" )) ]
394415
395416paramsDefinitionExampleJSON :: Value
396417paramsDefinitionExampleJSON = [aesonQQ|
@@ -420,8 +441,8 @@ paramsDefinitionExampleJSON = [aesonQQ|
420441
421442responsesDefinitionExample :: HashMap Text Response
422443responsesDefinitionExample =
423− [ ("NotFound", mempty { _responseDescription = "Entity not found." })
424− , ("IllegalInput", mempty { _responseDescription = "Illegal input for operation." }) ]
444+ [ ("NotFound", mempty & description .~ "Entity not found.")
445+ , ("IllegalInput", mempty & description .~ "Illegal input for operation.") ]
425446
426447responsesDefinitionExampleJSON :: Value
427448responsesDefinitionExampleJSON = [aesonQQ|
@@ -439,8 +460,8 @@ responsesDefinitionExampleJSON = [aesonQQ|
439460-- Responses Definition object
440461-- =======================================================================
441462
442−securityDefinitionsExample :: HashMap Text SecurityScheme
443−securityDefinitionsExample =
463+securityDefinitionsExample :: SecurityDefinitions
464+securityDefinitionsExample = SecurityDefinitions
444465 [ ("api_key", SecurityScheme
445466 { _securitySchemeType = SecuritySchemeApiKey (ApiKeyParams "api_key" ApiKeyHeader)
446467 , _securitySchemeDescription = Nothing })
@@ -472,50 +493,86 @@ securityDefinitionsExampleJSON = [aesonQQ|
472493}
473494|]
474495
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+
475536-- =======================================================================
476537-- Swagger object
477538-- =======================================================================
478539
479540swaggerExample :: Swagger
480541swaggerExample = mempty
481− { _swaggerBasePath = Just "/"
482− , _swaggerSchemes = Just [Http]
483− , _swaggerInfo = mempty
484− { _infoVersion = "1.0"
485− , _infoTitle = "Todo API"
486− , _infoLicense = Just License
487− { _licenseName = "MIT"
488− , _licenseUrl = Just (URL "http://mit.com") }
489− , _infoDescription = Just "This is a an API that tests servant-swagger support for a Todo API" }
490− , _swaggerPaths =
491− [ ("/todo/{id}", mempty
492− { _pathItemGet = Just mempty
493− { _operationResponses = mempty
494− { _responsesResponses =
495− [ (200, Inline mempty
496− { _responseSchema = Just $ Inline (mempty & type_ .~ SwaggerObject)
497− { _schemaExample = Just [aesonQQ|
498− {
499− "created": 100,
500− "description": "get milk"
501− } |]
502− , _schemaDescription = Just "This is some real Todo right here"
503− , _schemaProperties =
504− [ ("created", Inline $ mempty
505− & type_ .~ SwaggerInteger
506− & format ?~ "int32")
507− , ("description", Inline (mempty & type_ .~ SwaggerString)) ] }
508− , _responseDescription = "OK" }) ] }
509− , _operationProduces = Just (MimeList [ "application/json" ])
510− , _operationParameters =
511− [ Inline mempty
512− { _paramRequired = Just True
513− , _paramName = "id"
514− , _paramDescription = Just "TodoId param"
515− , _paramSchema = ParamOther $ mempty
516− & in_ .~ ParamPath
517− & type_ .~ SwaggerString } ]
518− , _operationTags = [ "todo" ] } }) ] }
542+ & basePath ?~ "/"
543+ & schemes ?~ [Http]
544+ & info .~ (mempty
545+ & version .~ "1.0"
546+ & title .~ "Todo API"
547+ & license ?~ "MIT"
548+ & license._Just.url ?~ URL "http://mit.com"
549+ & description ?~ "This is a an API that tests servant-swagger support for a Todo API")
550+ & paths.at "/todo/{id}" ?~ (mempty & get ?~ ((mempty :: Operation)
551+ & at 200 ?~ Inline (mempty
552+ & description .~ "OK"
553+ & schema ?~ Inline (mempty
554+ & type_ ?~ SwaggerObject
555+ & example ?~ [aesonQQ|
556+ {
557+ "created": 100,
558+ "description": "get milk"
559+ } |]
560+ & description ?~ "This is some real Todo right here"
561+ & properties .~
562+ [ ("created", Inline $ mempty
563+ & type_ ?~ SwaggerInteger
564+ & format ?~ "int32")
565+ , ("description", Inline (mempty & type_ ?~ SwaggerString))]))
566+ & produces ?~ MimeList [ "application/json" ]
567+ & parameters .~
568+ [ Inline $ mempty
569+ & required ?~ True
570+ & name .~ "id"
571+ & description ?~ "TodoId param"
572+ & schema .~ ParamOther (mempty
573+ & in_ .~ ParamPath
574+ & type_ ?~ SwaggerString ) ]
575+ & tags .~ InsOrdHS.fromList [ "todo" ] ))
519576
520577swaggerExampleJSON :: Value
521578swaggerExampleJSON = [aesonQQ|
@@ -582,130 +639,130 @@ swaggerExampleJSON = [aesonQQ|
582639
583640petstoreExampleJSON :: Value
584641petstoreExampleJSON = [aesonQQ|
585−{
642+{
586643 "swagger":"2.0",
587− "info":{
644+ "info":{
588645 "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.",
589646 "version":"1.0.0",
590647 "title":"Swagger Petstore",
591648 "termsOfService":"http://swagger.io/terms/",
592− "contact":{
649+ "contact":{
593650 "email":"apiteam@swagger.io"
594651 },
595− "license":{
652+ "license":{
596653 "name":"Apache 2.0",
597654 "url":"http://www.apache.org/licenses/LICENSE-2.0.html"
598655 }
599656 },
600657 "host":"petstore.swagger.io",
601658 "basePath":"/v2",
602− "tags":[
603− {
659+ "tags":[
660+ {
604661 "name":"pet",
605662 "description":"Everything about your Pets",
606− "externalDocs":{
663+ "externalDocs":{
607664 "description":"Find out more",
608665 "url":"http://swagger.io"
609666 }
610667 },
611− {
668+ {
612669 "name":"store",
613670 "description":"Access to Petstore orders"
614671 },
615− {
672+ {
616673 "name":"user",
617674 "description":"Operations about user",
618− "externalDocs":{
675+ "externalDocs":{
619676 "description":"Find out more about our store",
620677 "url":"http://swagger.io"
621678 }
622679 }
623680 ],
624− "schemes":[
681+ "schemes":[
625682 "http"
626683 ],
627− "paths":{
628− "/pet":{
629− "post":{
630− "tags":[
684+ "paths":{
685+ "/pet":{
686+ "post":{
687+ "tags":[
631688 "pet"
632689 ],
633690 "summary":"Add a new pet to the store",
634691 "description":"",
635692 "operationId":"addPet",
636− "consumes":[
693+ "consumes":[
637694 "application/json",
638695 "application/xml"
639696 ],
640− "produces":[
697+ "produces":[
641698 "application/xml",
642699 "application/json"
643700 ],
644− "parameters":[
645− {
701+ "parameters":[
702+ {
646703 "in":"body",
647704 "name":"body",
648705 "description":"Pet object that needs to be added to the store",
649706 "required":true,
650− "schema":{
707+ "schema":{
651708 "$ref":"#/definitions/Pet"
652709 }
653710 }
654711 ],
655− "responses":{
656− "405":{
712+ "responses":{
713+ "405":{
657714 "description":"Invalid input"
658715 }
659716 },
660− "security":[
661− {
662− "petstore_auth":[
717+ "security":[
718+ {
719+ "petstore_auth":[
663720 "write:pets",
664721 "read:pets"
665722 ]
666723 }
667724 ]
668725 },
669− "put":{
670− "tags":[
726+ "put":{
727+ "tags":[
671728 "pet"
672729 ],
673730 "summary":"Update an existing pet",
674731 "description":"",
675732 "operationId":"updatePet",
676− "consumes":[
733+ "consumes":[
677734 "application/json",
678735 "application/xml"
679736 ],
680− "produces":[
737+ "produces":[
681738 "application/xml",
682739 "application/json"
683740 ],
684− "parameters":[
685− {
741+ "parameters":[
742+ {
686743 "in":"body",
687744 "name":"body",
688745 "description":"Pet object that needs to be added to the store",
689746 "required":true,
690− "schema":{
747+ "schema":{
691748 "$ref":"#/definitions/Pet"
692749 }
693750 }
694751 ],
695− "responses":{
696− "400":{
752+ "responses":{
753+ "400":{
697754 "description":"Invalid ID supplied"
698755 },
699− "404":{
756+ "404":{
700757 "description":"Pet not found"
701758 },
702− "405":{
759+ "405":{
703760 "description":"Validation exception"
704761 }
705762 },
706− "security":[
707− {
708− "petstore_auth":[
763+ "security":[
764+ {
765+ "petstore_auth":[
709766 "write:pets",
710767 "read:pets"
711768 ]
@@ -713,28 +770,28 @@ petstoreExampleJSON = [aesonQQ|
713770 ]
714771 }
715772 },
716− "/pet/findByStatus":{
717− "get":{
718− "tags":[
773+ "/pet/findByStatus":{
774+ "get":{
775+ "tags":[
719776 "pet"
720777 ],
721778 "summary":"Finds Pets by status",
722779 "description":"Multiple status values can be provided with comma seperated strings",
723780 "operationId":"findPetsByStatus",
724− "produces":[
781+ "produces":[
725782 "application/xml",
726783 "application/json"
727784 ],
728− "parameters":[
729− {
785+ "parameters":[
786+ {
730787 "name":"status",
731788 "in":"query",
732789 "description":"Status values that need to be considered for filter",
733790 "required":true,
734791 "type":"array",
735− "items":{
792+ "items":{
736793 "type":"string",
737− "enum":[
794+ "enum":[
738795 "available",
739796 "pending",
740797 "sold"
@@ -744,23 +801,23 @@ petstoreExampleJSON = [aesonQQ|
744801 "collectionFormat":"csv"
745802 }
746803 ],
747− "responses":{
748− "200":{
804+ "responses":{
805+ "200":{
749806 "description":"successful operation",
750− "schema":{
807+ "schema":{
751808 "type":"array",
752− "items":{
809+ "items":{
753810 "$ref":"#/definitions/Pet"
754811 }
755812 }
756813 },
757− "400":{
814+ "400":{
758815 "description":"Invalid status value"
759816 }
760817 },
761− "security":[
762− {
763− "petstore_auth":[
818+ "security":[
819+ {
820+ "petstore_auth":[
764821 "write:pets",
765822 "read:pets"
766823 ]
@@ -768,48 +825,48 @@ petstoreExampleJSON = [aesonQQ|
768825 ]
769826 }
770827 },
771− "/pet/findByTags":{
772− "get":{
773− "tags":[
828+ "/pet/findByTags":{
829+ "get":{
830+ "tags":[
774831 "pet"
775832 ],
776833 "summary":"Finds Pets by tags",
777834 "description":"Muliple tags can be provided with comma seperated strings. Use tag1, tag2, tag3 for testing.",
778835 "operationId":"findPetsByTags",
779− "produces":[
836+ "produces":[
780837 "application/xml",
781838 "application/json"
782839 ],
783− "parameters":[
784− {
840+ "parameters":[
841+ {
785842 "name":"tags",
786843 "in":"query",
787844 "description":"Tags to filter by",
788845 "required":true,
789846 "type":"array",
790− "items":{
847+ "items":{
791848 "type":"string"
792849 },
793850 "collectionFormat":"csv"
794851 }
795852 ],
796− "responses":{
797− "200":{
853+ "responses":{
854+ "200":{
798855 "description":"successful operation",
799− "schema":{
856+ "schema":{
800857 "type":"array",
801− "items":{
858+ "items":{
802859 "$ref":"#/definitions/Pet"
803860 }
804861 }
805862 },
806− "400":{
863+ "400":{
807864 "description":"Invalid tag value"
808865 }
809866 },
810− "security":[
811− {
812− "petstore_auth":[
867+ "security":[
868+ {
869+ "petstore_auth":[
813870 "write:pets",
814871 "read:pets"
815872 ]
@@ -817,20 +874,20 @@ petstoreExampleJSON = [aesonQQ|
817874 ]
818875 }
819876 },
820− "/pet/{petId}":{
821− "get":{
822− "tags":[
877+ "/pet/{petId}":{
878+ "get":{
879+ "tags":[
823880 "pet"
824881 ],
825882 "summary":"Find pet by ID",
826883 "description":"Returns a single pet",
827884 "operationId":"getPetById",
828− "produces":[
885+ "produces":[
829886 "application/xml",
830887 "application/json"
831888 ],
832− "parameters":[
833− {
889+ "parameters":[
890+ {
834891 "name":"petId",
835892 "in":"path",
836893 "description":"ID of pet to return",
@@ -839,43 +896,42 @@ petstoreExampleJSON = [aesonQQ|
839896 "format":"int64"
840897 }
841898 ],
842− "responses":{
843− "200":{
899+ "responses":{
900+ "200":{
844901 "description":"successful operation",
845− "schema":{
902+ "schema":{
846903 "$ref":"#/definitions/Pet"
847904 }
848905 },
849− "400":{
906+ "400":{
850907 "description":"Invalid ID supplied"
851908 },
852− "404":{
909+ "404":{
853910 "description":"Pet not found"
854911 }
855912 },
856− "security":[
857− {
858− "api_key":[
859− ]
913+ "security":[
914+ {
915+ "api_key": []
860916 }
861917 ]
862918 },
863− "post":{
864− "tags":[
919+ "post":{
920+ "tags":[
865921 "pet"
866922 ],
867923 "summary":"Updates a pet in the store with form data",
868924 "description":"",
869925 "operationId":"updatePetWithForm",
870− "consumes":[
926+ "consumes":[
871927 "application/x-www-form-urlencoded"
872928 ],
873− "produces":[
929+ "produces":[
874930 "application/xml",
875931 "application/json"
876932 ],
877− "parameters":[
878− {
933+ "parameters":[
934+ {
879935 "name":"petId",
880936 "in":"path",
881937 "description":"ID of pet that needs to be updated",
@@ -883,14 +939,14 @@ petstoreExampleJSON = [aesonQQ|
883939 "type":"integer",
884940 "format":"int64"
885941 },
886− {
942+ {
887943 "name":"name",
888944 "in":"formData",
889945 "description":"Updated name of the pet",
890946 "required":false,
891947 "type":"string"
892948 },
893− {
949+ {
894950 "name":"status",
895951 "in":"formData",
896952 "description":"Updated status of the pet",
@@ -898,39 +954,39 @@ petstoreExampleJSON = [aesonQQ|
898954 "type":"string"
899955 }
900956 ],
901− "responses":{
902− "405":{
957+ "responses":{
958+ "405":{
903959 "description":"Invalid input"
904960 }
905961 },
906− "security":[
907− {
908− "petstore_auth":[
962+ "security":[
963+ {
964+ "petstore_auth":[
909965 "write:pets",
910966 "read:pets"
911967 ]
912968 }
913969 ]
914970 },
915− "delete":{
916− "tags":[
971+ "delete":{
972+ "tags":[
917973 "pet"
918974 ],
919975 "summary":"Deletes a pet",
920976 "description":"",
921977 "operationId":"deletePet",
922− "produces":[
978+ "produces":[
923979 "application/xml",
924980 "application/json"
925981 ],
926− "parameters":[
927− {
982+ "parameters":[
983+ {
928984 "name":"api_key",
929985 "in":"header",
930986 "required":false,
931987 "type":"string"
932988 },
933− {
989+ {
934990 "name":"petId",
935991 "in":"path",
936992 "description":"Pet id to delete",
@@ -939,14 +995,14 @@ petstoreExampleJSON = [aesonQQ|
939995 "format":"int64"
940996 }
941997 ],
942− "responses":{
943− "400":{
998+ "responses":{
999+ "400":{
9441000 "description":"Invalid pet value"
9451001 }
9461002 },
947− "security":[
948− {
949− "petstore_auth":[
1003+ "security":[
1004+ {
1005+ "petstore_auth":[
9501006 "write:pets",
9511007 "read:pets"
9521008 ]
@@ -954,22 +1010,22 @@ petstoreExampleJSON = [aesonQQ|
9541010 ]
9551011 }
9561012 },
957− "/pet/{petId}/uploadImage":{
958− "post":{
959− "tags":[
1013+ "/pet/{petId}/uploadImage":{
1014+ "post":{
1015+ "tags":[
9601016 "pet"
9611017 ],
9621018 "summary":"uploads an image",
9631019 "description":"",
9641020 "operationId":"uploadFile",
965− "consumes":[
1021+ "consumes":[
9661022 "multipart/form-data"
9671023 ],
968− "produces":[
1024+ "produces":[
9691025 "application/json"
9701026 ],
971− "parameters":[
972− {
1027+ "parameters":[
1028+ {
9731029 "name":"petId",
9741030 "in":"path",
9751031 "description":"ID of pet to update",
@@ -977,14 +1033,14 @@ petstoreExampleJSON = [aesonQQ|
9771033 "type":"integer",
9781034 "format":"int64"
9791035 },
980− {
1036+ {
9811037 "name":"additionalMetadata",
9821038 "in":"formData",
9831039 "description":"Additional data to pass to server",
9841040 "required":false,
9851041 "type":"string"
9861042 },
987− {
1043+ {
9881044 "name":"file",
9891045 "in":"formData",
9901046 "description":"file to upload",
@@ -992,17 +1048,17 @@ petstoreExampleJSON = [aesonQQ|
9921048 "type":"file"
9931049 }
9941050 ],
995− "responses":{
996− "200":{
1051+ "responses":{
1052+ "200":{
9971053 "description":"successful operation",
998− "schema":{
1054+ "schema":{
9991055 "$ref":"#/definitions/ApiResponse"
10001056 }
10011057 }
10021058 },
1003− "security":[
1004− {
1005− "petstore_auth":[
1059+ "security":[
1060+ {
1061+ "petstore_auth":[
10061062 "write:pets",
10071063 "read:pets"
10081064 ]
@@ -1010,89 +1066,87 @@ petstoreExampleJSON = [aesonQQ|
10101066 ]
10111067 }
10121068 },
1013− "/store/inventory":{
1014− "get":{
1015− "tags":[
1069+ "/store/inventory":{
1070+ "get":{
1071+ "tags":[
10161072 "store"
10171073 ],
10181074 "summary":"Returns pet inventories by status",
10191075 "description":"Returns a map of status codes to quantities",
10201076 "operationId":"getInventory",
1021− "produces":[
1077+ "produces":[
10221078 "application/json"
10231079 ],
1024− "parameters":[
1025− ],
1026− "responses":{
1027− "200":{
1080+ "parameters": [],
1081+ "responses":{
1082+ "200":{
10281083 "description":"successful operation",
1029− "schema":{
1084+ "schema":{
10301085 "type":"object",
1031− "additionalProperties":{
1086+ "additionalProperties":{
10321087 "type":"integer",
10331088 "format":"int32"
10341089 }
10351090 }
10361091 }
10371092 },
1038− "security":[
1039− {
1040− "api_key":[
1041− ]
1093+ "security":[
1094+ {
1095+ "api_key": []
10421096 }
10431097 ]
10441098 }
10451099 },
1046− "/store/order":{
1047− "post":{
1048− "tags":[
1100+ "/store/order":{
1101+ "post":{
1102+ "tags":[
10491103 "store"
10501104 ],
10511105 "summary":"Place an order for a pet",
10521106 "description":"",
10531107 "operationId":"placeOrder",
1054− "produces":[
1108+ "produces":[
10551109 "application/xml",
10561110 "application/json"
10571111 ],
1058− "parameters":[
1059− {
1112+ "parameters":[
1113+ {
10601114 "in":"body",
10611115 "name":"body",
10621116 "description":"order placed for purchasing the pet",
10631117 "required":true,
1064− "schema":{
1118+ "schema":{
10651119 "$ref":"#/definitions/Order"
10661120 }
10671121 }
10681122 ],
1069− "responses":{
1070− "200":{
1123+ "responses":{
1124+ "200":{
10711125 "description":"successful operation",
1072− "schema":{
1126+ "schema":{
10731127 "$ref":"#/definitions/Order"
10741128 }
10751129 },
1076− "400":{
1130+ "400":{
10771131 "description":"Invalid Order"
10781132 }
10791133 }
10801134 }
10811135 },
1082− "/store/order/{orderId}":{
1083− "get":{
1084− "tags":[
1136+ "/store/order/{orderId}":{
1137+ "get":{
1138+ "tags":[
10851139 "store"
10861140 ],
10871141 "summary":"Find purchase order by ID",
10881142 "description":"For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",
10891143 "operationId":"getOrderById",
1090− "produces":[
1144+ "produces":[
10911145 "application/xml",
10921146 "application/json"
10931147 ],
1094− "parameters":[
1095− {
1148+ "parameters":[
1149+ {
10961150 "name":"orderId",
10971151 "in":"path",
10981152 "description":"ID of pet that needs to be fetched",
@@ -1103,34 +1157,34 @@ petstoreExampleJSON = [aesonQQ|
11031157 "format":"int64"
11041158 }
11051159 ],
1106− "responses":{
1107− "200":{
1160+ "responses":{
1161+ "200":{
11081162 "description":"successful operation",
1109− "schema":{
1163+ "schema":{
11101164 "$ref":"#/definitions/Order"
11111165 }
11121166 },
1113− "400":{
1167+ "400":{
11141168 "description":"Invalid ID supplied"
11151169 },
1116− "404":{
1170+ "404":{
11171171 "description":"Order not found"
11181172 }
11191173 }
11201174 },
1121− "delete":{
1122− "tags":[
1175+ "delete":{
1176+ "tags":[
11231177 "store"
11241178 ],
11251179 "summary":"Delete purchase order by ID",
11261180 "description":"For valid response try integer IDs with value < 1000. Anything above 1000 or nonintegers will generate API errors",
11271181 "operationId":"deleteOrder",
1128− "produces":[
1182+ "produces":[
11291183 "application/xml",
11301184 "application/json"
11311185 ],
1132− "parameters":[
1133− {
1186+ "parameters":[
1187+ {
11341188 "name":"orderId",
11351189 "in":"path",
11361190 "description":"ID of the order that needs to be deleted",
@@ -1139,133 +1193,133 @@ petstoreExampleJSON = [aesonQQ|
11391193 "minimum":1.0
11401194 }
11411195 ],
1142− "responses":{
1143− "400":{
1196+ "responses":{
1197+ "400":{
11441198 "description":"Invalid ID supplied"
11451199 },
1146− "404":{
1200+ "404":{
11471201 "description":"Order not found"
11481202 }
11491203 }
11501204 }
11511205 },
1152− "/user":{
1153− "post":{
1154− "tags":[
1206+ "/user":{
1207+ "post":{
1208+ "tags":[
11551209 "user"
11561210 ],
11571211 "summary":"Create user",
11581212 "description":"This can only be done by the logged in user.",
11591213 "operationId":"createUser",
1160− "produces":[
1214+ "produces":[
11611215 "application/xml",
11621216 "application/json"
11631217 ],
1164− "parameters":[
1165− {
1218+ "parameters":[
1219+ {
11661220 "in":"body",
11671221 "name":"body",
11681222 "description":"Created user object",
11691223 "required":true,
1170− "schema":{
1224+ "schema":{
11711225 "$ref":"#/definitions/User"
11721226 }
11731227 }
11741228 ],
1175− "responses":{
1176− "default":{
1229+ "responses":{
1230+ "default":{
11771231 "description":"successful operation"
11781232 }
11791233 }
11801234 }
11811235 },
1182− "/user/createWithArray":{
1183− "post":{
1184− "tags":[
1236+ "/user/createWithArray":{
1237+ "post":{
1238+ "tags":[
11851239 "user"
11861240 ],
11871241 "summary":"Creates list of users with given input array",
11881242 "description":"",
11891243 "operationId":"createUsersWithArrayInput",
1190− "produces":[
1244+ "produces":[
11911245 "application/xml",
11921246 "application/json"
11931247 ],
1194− "parameters":[
1195− {
1248+ "parameters":[
1249+ {
11961250 "in":"body",
11971251 "name":"body",
11981252 "description":"List of user object",
11991253 "required":true,
1200− "schema":{
1254+ "schema":{
12011255 "type":"array",
1202− "items":{
1256+ "items":{
12031257 "$ref":"#/definitions/User"
12041258 }
12051259 }
12061260 }
12071261 ],
1208− "responses":{
1209− "default":{
1262+ "responses":{
1263+ "default":{
12101264 "description":"successful operation"
12111265 }
12121266 }
12131267 }
12141268 },
1215− "/user/createWithList":{
1216− "post":{
1217− "tags":[
1269+ "/user/createWithList":{
1270+ "post":{
1271+ "tags":[
12181272 "user"
12191273 ],
12201274 "summary":"Creates list of users with given input array",
12211275 "description":"",
12221276 "operationId":"createUsersWithListInput",
1223− "produces":[
1277+ "produces":[
12241278 "application/xml",
12251279 "application/json"
12261280 ],
1227− "parameters":[
1228− {
1281+ "parameters":[
1282+ {
12291283 "in":"body",
12301284 "name":"body",
12311285 "description":"List of user object",
12321286 "required":true,
1233− "schema":{
1287+ "schema":{
12341288 "type":"array",
1235− "items":{
1289+ "items":{
12361290 "$ref":"#/definitions/User"
12371291 }
12381292 }
12391293 }
12401294 ],
1241− "responses":{
1242− "default":{
1295+ "responses":{
1296+ "default":{
12431297 "description":"successful operation"
12441298 }
12451299 }
12461300 }
12471301 },
1248− "/user/login":{
1249− "get":{
1250− "tags":[
1302+ "/user/login":{
1303+ "get":{
1304+ "tags":[
12511305 "user"
12521306 ],
12531307 "summary":"Logs user into the system",
12541308 "description":"",
12551309 "operationId":"loginUser",
1256− "produces":[
1310+ "produces":[
12571311 "application/xml",
12581312 "application/json"
12591313 ],
1260− "parameters":[
1261− {
1314+ "parameters":[
1315+ {
12621316 "name":"username",
12631317 "in":"query",
12641318 "description":"The user name for login",
12651319 "required":true,
12661320 "type":"string"
12671321 },
1268− {
1322+ {
12691323 "name":"password",
12701324 "in":"query",
12711325 "description":"The password for login in clear text",
@@ -1273,66 +1327,65 @@ petstoreExampleJSON = [aesonQQ|
12731327 "type":"string"
12741328 }
12751329 ],
1276− "responses":{
1277− "200":{
1330+ "responses":{
1331+ "200":{
12781332 "description":"successful operation",
1279− "schema":{
1333+ "schema":{
12801334 "type":"string"
12811335 },
1282− "headers":{
1283− "X-Rate-Limit":{
1336+ "headers":{
1337+ "X-Rate-Limit":{
12841338 "type":"integer",
12851339 "format":"int32",
12861340 "description":"calls per hour allowed by the user"
12871341 },
1288− "X-Expires-After":{
1342+ "X-Expires-After":{
12891343 "type":"string",
12901344 "format":"date-time",
12911345 "description":"date in UTC when toekn expires"
12921346 }
12931347 }
12941348 },
1295− "400":{
1349+ "400":{
12961350 "description":"Invalid username/password supplied"
12971351 }
12981352 }
12991353 }
13001354 },
1301− "/user/logout":{
1302− "get":{
1303− "tags":[
1355+ "/user/logout":{
1356+ "get":{
1357+ "tags":[
13041358 "user"
13051359 ],
13061360 "summary":"Logs out current logged in user session",
13071361 "description":"",
13081362 "operationId":"logoutUser",
1309− "produces":[
1363+ "produces":[
13101364 "application/xml",
13111365 "application/json"
13121366 ],
1313− "parameters":[
1314− ],
1315− "responses":{
1316− "default":{
1367+ "parameters": [],
1368+ "responses":{
1369+ "default":{
13171370 "description":"successful operation"
13181371 }
13191372 }
13201373 }
13211374 },
1322− "/user/{username}":{
1323− "get":{
1324− "tags":[
1375+ "/user/{username}":{
1376+ "get":{
1377+ "tags":[
13251378 "user"
13261379 ],
13271380 "summary":"Get user by user name",
13281381 "description":"",
13291382 "operationId":"getUserByName",
1330− "produces":[
1383+ "produces":[
13311384 "application/xml",
13321385 "application/json"
13331386 ],
1334− "parameters":[
1335− {
1387+ "parameters":[
1388+ {
13361389 "name":"username",
13371390 "in":"path",
13381391 "description":"The name that needs to be fetched. Use user1 for testing. ",
@@ -1340,72 +1393,72 @@ petstoreExampleJSON = [aesonQQ|
13401393 "type":"string"
13411394 }
13421395 ],
1343− "responses":{
1344− "200":{
1396+ "responses":{
1397+ "200":{
13451398 "description":"successful operation",
1346− "schema":{
1399+ "schema":{
13471400 "$ref":"#/definitions/User"
13481401 }
13491402 },
1350− "400":{
1403+ "400":{
13511404 "description":"Invalid username supplied"
13521405 },
1353− "404":{
1406+ "404":{
13541407 "description":"User not found"
13551408 }
13561409 }
13571410 },
1358− "put":{
1359− "tags":[
1411+ "put":{
1412+ "tags":[
13601413 "user"
13611414 ],
13621415 "summary":"Updated user",
13631416 "description":"This can only be done by the logged in user.",
13641417 "operationId":"updateUser",
1365− "produces":[
1418+ "produces":[
13661419 "application/xml",
13671420 "application/json"
13681421 ],
1369− "parameters":[
1370− {
1422+ "parameters":[
1423+ {
13711424 "name":"username",
13721425 "in":"path",
13731426 "description":"name that need to be deleted",
13741427 "required":true,
13751428 "type":"string"
13761429 },
1377− {
1430+ {
13781431 "in":"body",
13791432 "name":"body",
13801433 "description":"Updated user object",
13811434 "required":true,
1382− "schema":{
1435+ "schema":{
13831436 "$ref":"#/definitions/User"
13841437 }
13851438 }
13861439 ],
1387− "responses":{
1388− "400":{
1440+ "responses":{
1441+ "400":{
13891442 "description":"Invalid user supplied"
13901443 },
1391− "404":{
1444+ "404":{
13921445 "description":"User not found"
13931446 }
13941447 }
13951448 },
1396− "delete":{
1397− "tags":[
1449+ "delete":{
1450+ "tags":[
13981451 "user"
13991452 ],
14001453 "summary":"Delete user",
14011454 "description":"This can only be done by the logged in user.",
14021455 "operationId":"deleteUser",
1403− "produces":[
1456+ "produces":[
14041457 "application/xml",
14051458 "application/json"
14061459 ],
1407− "parameters":[
1408− {
1460+ "parameters":[
1461+ {
14091462 "name":"username",
14101463 "in":"path",
14111464 "description":"The name that needs to be deleted",
@@ -1413,207 +1466,237 @@ petstoreExampleJSON = [aesonQQ|
14131466 "type":"string"
14141467 }
14151468 ],
1416− "responses":{
1417− "400":{
1469+ "responses":{
1470+ "400":{
14181471 "description":"Invalid username supplied"
14191472 },
1420− "404":{
1473+ "404":{
14211474 "description":"User not found"
14221475 }
14231476 }
14241477 }
14251478 }
14261479 },
1427− "securityDefinitions":{
1428− "petstore_auth":{
1480+ "securityDefinitions":{
1481+ "petstore_auth":{
14291482 "type":"oauth2",
14301483 "authorizationUrl":"http://petstore.swagger.io/api/oauth/dialog",
14311484 "flow":"implicit",
1432− "scopes":{
1485+ "scopes":{
14331486 "write:pets":"modify pets in your account",
14341487 "read:pets":"read your pets"
14351488 }
14361489 },
1437− "api_key":{
1490+ "api_key":{
14381491 "type":"apiKey",
14391492 "name":"api_key",
14401493 "in":"header"
14411494 }
14421495 },
1443− "definitions":{
1444− "Order":{
1496+ "definitions":{
1497+ "Order":{
14451498 "type":"object",
1446− "properties":{
1447− "id":{
1499+ "properties":{
1500+ "id":{
14481501 "type":"integer",
14491502 "format":"int64"
14501503 },
1451− "petId":{
1504+ "petId":{
14521505 "type":"integer",
14531506 "format":"int64"
14541507 },
1455− "quantity":{
1508+ "quantity":{
14561509 "type":"integer",
14571510 "format":"int32"
14581511 },
1459− "shipDate":{
1512+ "shipDate":{
14601513 "type":"string",
14611514 "format":"date-time"
14621515 },
1463− "status":{
1516+ "status":{
14641517 "type":"string",
14651518 "description":"Order Status",
1466− "enum":[
1519+ "enum":[
14671520 "placed",
14681521 "approved",
14691522 "delivered"
14701523 ]
14711524 },
1472− "complete":{
1525+ "complete":{
14731526 "type":"boolean",
14741527 "default":false
14751528 }
14761529 },
1477− "xml":{
1530+ "xml":{
14781531 "name":"Order"
14791532 }
14801533 },
1481− "Category":{
1534+ "Category":{
14821535 "type":"object",
1483− "properties":{
1484− "id":{
1536+ "properties":{
1537+ "id":{
14851538 "type":"integer",
14861539 "format":"int64"
14871540 },
1488− "name":{
1541+ "name":{
14891542 "type":"string"
14901543 }
14911544 },
1492− "xml":{
1545+ "xml":{
14931546 "name":"Category"
14941547 }
14951548 },
1496− "User":{
1549+ "User":{
14971550 "type":"object",
1498− "properties":{
1499− "id":{
1551+ "properties":{
1552+ "id":{
15001553 "type":"integer",
15011554 "format":"int64"
15021555 },
1503− "username":{
1556+ "username":{
15041557 "type":"string"
15051558 },
1506− "firstName":{
1559+ "firstName":{
15071560 "type":"string"
15081561 },
1509− "lastName":{
1562+ "lastName":{
15101563 "type":"string"
15111564 },
1512− "email":{
1565+ "email":{
15131566 "type":"string"
15141567 },
1515− "password":{
1568+ "password":{
15161569 "type":"string"
15171570 },
1518− "phone":{
1571+ "phone":{
15191572 "type":"string"
15201573 },
1521− "userStatus":{
1574+ "userStatus":{
15221575 "type":"integer",
15231576 "format":"int32",
15241577 "description":"User Status"
15251578 }
15261579 },
1527− "xml":{
1580+ "xml":{
15281581 "name":"User"
15291582 }
15301583 },
1531− "Tag":{
1584+ "Tag":{
15321585 "type":"object",
1533− "properties":{
1534− "id":{
1586+ "properties":{
1587+ "id":{
15351588 "type":"integer",
15361589 "format":"int64"
15371590 },
1538− "name":{
1591+ "name":{
15391592 "type":"string"
15401593 }
15411594 },
1542− "xml":{
1595+ "xml":{
15431596 "name":"Tag"
15441597 }
15451598 },
1546− "Pet":{
1599+ "Pet":{
15471600 "type":"object",
1548− "required":[
1601+ "required":[
15491602 "name",
15501603 "photoUrls"
15511604 ],
1552− "properties":{
1553− "id":{
1605+ "properties":{
1606+ "id":{
15541607 "type":"integer",
15551608 "format":"int64"
15561609 },
1557− "category":{
1610+ "category":{
15581611 "$ref":"#/definitions/Category"
15591612 },
1560− "name":{
1613+ "name":{
15611614 "type":"string",
15621615 "example":"doggie"
15631616 },
1564− "photoUrls":{
1617+ "photoUrls":{
15651618 "type":"array",
1566− "xml":{
1619+ "xml":{
15671620 "name":"photoUrl",
15681621 "wrapped":true
15691622 },
1570− "items":{
1623+ "items":{
15711624 "type":"string"
15721625 }
15731626 },
1574− "tags":{
1627+ "tags":{
15751628 "type":"array",
1576− "xml":{
1629+ "xml":{
15771630 "name":"tag",
15781631 "wrapped":true
15791632 },
1580− "items":{
1633+ "items":{
15811634 "$ref":"#/definitions/Tag"
15821635 }
15831636 },
1584− "status":{
1637+ "status":{
15851638 "type":"string",
15861639 "description":"pet status in the store",
1587− "enum":[
1640+ "enum":[
15881641 "available",
15891642 "pending",
15901643 "sold"
15911644 ]
15921645 }
15931646 },
1594− "xml":{
1647+ "xml":{
15951648 "name":"Pet"
15961649 }
15971650 },
1598− "ApiResponse":{
1651+ "ApiResponse":{
15991652 "type":"object",
1600− "properties":{
1601− "code":{
1653+ "properties":{
1654+ "code":{
16021655 "type":"integer",
16031656 "format":"int32"
16041657 },
1605− "type":{
1658+ "type":{
16061659 "type":"string"
16071660 },
1608− "message":{
1661+ "message":{
16091662 "type":"string"
16101663 }
16111664 }
16121665 }
16131666 },
1614− "externalDocs":{
1667+ "externalDocs":{
16151668 "description":"Find out more about Swagger",
16161669 "url":"http://swagger.io"
16171670 }
16181671}
16191672|]
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−7
@@ -1,7 +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
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