feat: Add OpenAPI route (#1960)

## Relevant issue(s)

Resolves #510 

## Description

This PR adds an HTTP endpoint that returns an OpenAPI specification for
DefraDB. The definitions are part code generation and part hand written.
This should work well for adding examples and more documentation in the
future.

## Tasks

- [x] I made sure the code is well commented, particularly
hard-to-understand areas.
- [x] I made sure the repository-held documentation is changed
accordingly.
- [x] I made sure the pull request title adheres to the conventional
commit style (the subset used in the project can be found in
[tools/configs/chglog/config.yml](tools/configs/chglog/config.yml)).
- [x] I made sure to discuss its limitations such as threats to
validity, vulnerability to mistake and misuse, robustness to
invalidation of assumptions, resource requirements, ...

## How has this been tested?

View endpoint in browser `localhost:9181/api/v0/openapi`.

Double checked with OpenAPI validator tool.

Specify the platform(s) on which this was tested:
- MacOS

cli/start.go

@@ -274,9 +274,12 @@ func start(ctx context.Context, cfg *config.Config) (*defraInstance, error) {
 
 	var server *httpapi.Server
 	if node != nil {
-		server = httpapi.NewServer(node, sOpt...)
+		server, err = httpapi.NewServer(node, sOpt...)
 	} else {
-		server = httpapi.NewServer(db, sOpt...)
+		server, err = httpapi.NewServer(db, sOpt...)
+	}
+	if err != nil {
+		return nil, errors.Wrap("failed to create http server", err)
 	}
 	if err := server.Listen(ctx); err != nil {
 		return nil, errors.Wrap(fmt.Sprintf("failed to listen on TCP address %v", server.Addr), err)

go.mod

@@ -8,6 +8,7 @@ require (
 	github.com/dgraph-io/badger/v4 v4.1.0
 	github.com/evanphx/json-patch/v5 v5.7.0
 	github.com/fxamacker/cbor/v2 v2.5.0
+	github.com/getkin/kin-openapi v0.120.0
 	github.com/go-chi/chi/v5 v5.0.10
 	github.com/go-chi/cors v1.2.1
 	github.com/go-errors/errors v1.5.1
@@ -73,6 +74,8 @@ require (
 	github.com/fsnotify/fsnotify v1.6.0 // indirect
 	github.com/go-logr/logr v1.2.4 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/go-openapi/jsonpointer v0.19.6 // indirect
+	github.com/go-openapi/swag v0.22.4 // indirect
 	github.com/go-task/slim-sprig v0.0.0-20230315185526-52ccab3ef572 // indirect
 	github.com/godbus/dbus/v5 v5.1.0 // indirect
 	github.com/gogo/protobuf v1.3.2 // indirect
@@ -95,6 +98,7 @@ require (
 	github.com/hsanjuan/ipfs-lite v1.4.1 // indirect
 	github.com/huin/goupnp v1.2.0 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/invopop/yaml v0.2.0 // indirect
 	github.com/ipfs/bbloom v0.0.4 // indirect
 	github.com/ipfs/go-bitswap v0.12.0 // indirect
 	github.com/ipfs/go-blockservice v0.5.1 // indirect
@@ -119,6 +123,7 @@ require (
 	github.com/ipld/go-ipld-prime v0.21.0 // indirect
 	github.com/jackpal/go-nat-pmp v1.0.2 // indirect
 	github.com/jbenet/go-temp-err-catcher v0.1.0 // indirect
+	github.com/josharian/intern v1.0.0 // indirect
 	github.com/klauspost/compress v1.17.0 // indirect
 	github.com/klauspost/cpuid/v2 v2.2.5 // indirect
 	github.com/koron/go-ssdp v0.0.4 // indirect
@@ -136,13 +141,15 @@ require (
 	github.com/libp2p/go-reuseport v0.4.0 // indirect
 	github.com/libp2p/go-yamux/v4 v4.0.1 // indirect
 	github.com/magiconair/properties v1.8.7 // indirect
+	github.com/mailru/easyjson v0.7.7 // indirect
 	github.com/marten-seemann/tcp v0.0.0-20210406111302-dfbc87cc63fd // indirect
 	github.com/mattn/go-isatty v0.0.19 // indirect
 	github.com/matttproud/golang_protobuf_extensions v1.0.4 // indirect
 	github.com/miekg/dns v1.1.55 // indirect
 	github.com/mikioh/tcpinfo v0.0.0-20190314235526-30a79bb1804b // indirect
 	github.com/mikioh/tcpopt v0.0.0-20190314235656-172688c1accc // indirect
 	github.com/minio/sha256-simd v1.0.1 // indirect
+	github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 // indirect
 	github.com/mr-tron/base58 v1.2.0 // indirect
 	github.com/multiformats/go-base32 v0.1.0 // indirect
 	github.com/multiformats/go-base36 v0.2.0 // indirect
@@ -156,6 +163,7 @@ require (
 	github.com/opentracing/opentracing-go v1.2.0 // indirect
 	github.com/pbnjay/memory v0.0.0-20210728143218-7b4eea64cf58 // indirect
 	github.com/pelletier/go-toml/v2 v2.1.0 // indirect
+	github.com/perimeterx/marshmallow v1.1.5 // indirect
 	github.com/pkg/errors v0.9.1 // indirect
 	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
 	github.com/polydawn/refmt v0.89.0 // indirect

go.sum

@@ -152,6 +152,7 @@ github.com/cpuguy83/go-md2man/v2 v2.0.2/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46t
 github.com/crackcomm/go-gitignore v0.0.0-20170627025303-887ab5e44cc3 h1:HVTnpeuvF6Owjd5mniCL8DEXo7uYXdQEmOP4FJbV5tg=
 github.com/crackcomm/go-gitignore v0.0.0-20170627025303-887ab5e44cc3/go.mod h1:p1d6YEZWvFzEh4KLyvBcVSnrfNDDvK2zfK/4x2v/4pE=
 github.com/creack/pty v1.1.7/go.mod h1:lj5s0c3V2DBrqTV7llrYr5NG6My20zk30Fl46Y7DoTY=
+github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/cskr/pubsub v1.0.2 h1:vlOzMhl6PFn60gRlTQQsIfVwaPB/B/8MziK8FhEPt/0=
 github.com/cskr/pubsub v1.0.2/go.mod h1:/8MzYXk/NJAz782G8RPkFzXTZVu63VotefPnR9TIRis=
 github.com/davecgh/go-spew v0.0.0-20171005155431-ecdeabc65495/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
@@ -218,6 +219,8 @@ github.com/fsnotify/fsnotify v1.6.0 h1:n+5WquG0fcWoWp6xPWfHdbskMCQaFnG6PfBrh1Ky4
 github.com/fsnotify/fsnotify v1.6.0/go.mod h1:sl3t1tCWJFWoRz9R8WJCbQihKKwmorjAbSClcnxKAGw=
 github.com/fxamacker/cbor/v2 v2.5.0 h1:oHsG0V/Q6E/wqTS2O1Cozzsy69nqCiguo5Q1a1ADivE=
 github.com/fxamacker/cbor/v2 v2.5.0/go.mod h1:TA1xS00nchWmaBnEIxPSE5oHLuJBAVvqrtAnWBwBCVo=
+github.com/getkin/kin-openapi v0.120.0 h1:MqJcNJFrMDFNc07iwE8iFC5eT2k/NPUFDIpNeiZv8Jg=
+github.com/getkin/kin-openapi v0.120.0/go.mod h1:PCWw/lfBrJY4HcdqE3jj+QFkaFK8ABoqo7PvqVhXXqw=
 github.com/ghodss/yaml v1.0.0/go.mod h1:4dBDuWmgqj2HViK6kFavaiC9ZROes6MMH2rRYeMEF04=
 github.com/gliderlabs/ssh v0.1.1/go.mod h1:U7qILu1NlMHj9FlMhZLlkCdDnU1DBEAqr0aevW3Awn0=
 github.com/go-check/check v0.0.0-20180628173108-788fd7840127/go.mod h1:9ES+weclKsC9YodN5RgxqK/VD9HM9JsCSh7rNhMZE98=
@@ -242,10 +245,16 @@ github.com/go-logr/logr v1.2.4 h1:g01GSCwiDw2xSZfjJ2/T9M+S6pFdcNtFYsp+Y43HYDQ=
 github.com/go-logr/logr v1.2.4/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
 github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
 github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
+github.com/go-openapi/jsonpointer v0.19.6 h1:eCs3fxoIi3Wh6vtgmLTOjdhSpiqphQ+DaPn38N2ZdrE=
+github.com/go-openapi/jsonpointer v0.19.6/go.mod h1:osyAmYz/mB/C3I+WsTTSgw1ONzaLJoLCyoi6/zppojs=
+github.com/go-openapi/swag v0.22.3/go.mod h1:UzaqsxGiab7freDnrUUra0MwWfN/q7tE4j+VcZ0yl14=
+github.com/go-openapi/swag v0.22.4 h1:QLMzNJnMGPRNDCbySlcj1x01tzU8/9LTTL9hZZZogBU=
+github.com/go-openapi/swag v0.22.4/go.mod h1:UzaqsxGiab7freDnrUUra0MwWfN/q7tE4j+VcZ0yl14=
 github.com/go-sql-driver/mysql v1.4.0/go.mod h1:zAC/RDZ24gD3HViQzih4MyKcchzm+sOG5ZlKdlhCg5w=
 github.com/go-stack/stack v1.8.0/go.mod h1:v0f6uXyyMGvRgIKkXu+yp6POWl0qKG85gN/melR3HDY=
 github.com/go-task/slim-sprig v0.0.0-20230315185526-52ccab3ef572 h1:tfuBGBXKqDEevZMzYi5KSi8KkcZtzBcTgAUUtapy0OI=
 github.com/go-task/slim-sprig v0.0.0-20230315185526-52ccab3ef572/go.mod h1:9Pwr4B2jHnOSGXyyzV8ROjYa2ojvAY6HCGYYfMoC3Ls=
+github.com/go-test/deep v1.0.8 h1:TDsG77qcSprGbC6vTN8OuXp5g+J+b5Pcguhf7Zt61VM=
 github.com/go-yaml/yaml v2.1.0+incompatible/go.mod h1:w2MrLa16VYP0jy6N7M5kHaCkaLENm+P+Tv+MfurjSw0=
 github.com/godbus/dbus/v5 v5.0.3/go.mod h1:xhWf0FNVPg57R7Z0UbKHbJfkEywrmjJnf7w5xrFpKfA=
 github.com/godbus/dbus/v5 v5.0.4/go.mod h1:xhWf0FNVPg57R7Z0UbKHbJfkEywrmjJnf7w5xrFpKfA=
@@ -419,6 +428,8 @@ github.com/inconshreveable/mousetrap v1.0.0/go.mod h1:PxqpIevigyE2G7u3NXJIT2ANyt
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
 github.com/influxdata/influxdb1-client v0.0.0-20191209144304-8bf82d3c094d/go.mod h1:qj24IKcXYK6Iy9ceXlo3Tc+vtHo9lIhSX5JddghvEPo=
+github.com/invopop/yaml v0.2.0 h1:7zky/qH+O0DwAyoobXUqvVBwgBFRxKoQ/3FjcVpjTMY=
+github.com/invopop/yaml v0.2.0/go.mod h1:2XuRLgs/ouIrW3XNzuNj7J3Nvu/Dig5MXvbCEdiBN3Q=
 github.com/ipfs/bbloom v0.0.1/go.mod h1:oqo8CVWsJFMOZqTglBG4wydCE4IQA/G2/SEofB0rjUI=
 github.com/ipfs/bbloom v0.0.4 h1:Gi+8EGJ2y5qiD5FbsbpX/TMNcJw8gSqr7eyjHa4Fhvs=
 github.com/ipfs/bbloom v0.0.4/go.mod h1:cS9YprKXpoZ9lT0n/Mw/a6/aFV6DTjTLYHeA+gyqMG0=
@@ -593,6 +604,8 @@ github.com/jessevdk/go-flags v0.0.0-20141203071132-1679536dcc89/go.mod h1:4FA24M
 github.com/jessevdk/go-flags v1.4.0/go.mod h1:4FA24M0QyGHXBuZZK/XkWh8h0e1EYbRYJSGM75WSRxI=
 github.com/jmespath/go-jmespath v0.0.0-20180206201540-c2b33e8439af/go.mod h1:Nht3zPeWKUH0NzdCt2Blrr5ys8VGpn0CEB0cQHVjt7k=
 github.com/jonboulle/clockwork v0.1.0/go.mod h1:Ii8DK3G1RaLaWxj9trq07+26W01tbo22gdxWY5EU2bo=
+github.com/josharian/intern v1.0.0 h1:vlS4z54oSdjm0bgjRigI+G1HpF+tI+9rE5LLzOg8HmY=
+github.com/josharian/intern v1.0.0/go.mod h1:5DoeVV0s6jJacbCEi61lwdGj/aVlrQvzHFFd8Hwg//Y=
 github.com/jpillora/backoff v1.0.0/go.mod h1:J/6gKK9jxlEcS3zixgDgUAsiuZ7yrSoa/FX5e0EB2j4=
 github.com/jrick/logrotate v1.0.0/go.mod h1:LNinyqDIJnpAur+b8yyulnQw/wDuN1+BYKlTRt3OuAQ=
 github.com/json-iterator/go v1.1.6/go.mod h1:+SdeFBvtyEkXs7REEP0seUULqWtbJapLOCVDaaPEHmU=
@@ -633,6 +646,7 @@ github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
 github.com/kr/pty v1.1.3/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
 github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
 github.com/lens-vm/lens/host-go v0.0.0-20230729032926-5acb4df9bd25 h1:hC67vWtvuDnw8w6u4jLFoj3SOH92/4Lq8SCR++L7njw=
 github.com/lens-vm/lens/host-go v0.0.0-20230729032926-5acb4df9bd25/go.mod h1:rDE4oJUIAQoXX9heUg8VOQf5LscRWj0BeE5mbGqOs3E=
 github.com/libp2p/go-addr-util v0.0.1/go.mod h1:4ac6O7n9rIAKB1dnd+s8IbbMXkt+oBpzX4/+RACcnlQ=
@@ -897,6 +911,8 @@ github.com/magiconair/properties v1.8.7 h1:IeQXZAiQcpL9mgcAe1Nu6cX9LLw6ExEHKjN0V
 github.com/magiconair/properties v1.8.7/go.mod h1:Dhd985XPs7jluiymwWYZ0G4Z61jb3vdS329zhj2hYo0=
 github.com/mailru/easyjson v0.0.0-20180823135443-60711f1a8329/go.mod h1:C1wdFJiN94OJF2b5HbByQZoLdCWB1Yqtg26g4irojpc=
 github.com/mailru/easyjson v0.0.0-20190312143242-1de009706dbe/go.mod h1:C1wdFJiN94OJF2b5HbByQZoLdCWB1Yqtg26g4irojpc=
+github.com/mailru/easyjson v0.7.7 h1:UGYAvKxe3sBsEDzO8ZeWOSlIQfWFlxbzLZe7hwFURr0=
+github.com/mailru/easyjson v0.7.7/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc=
 github.com/marten-seemann/qpack v0.2.1/go.mod h1:F7Gl5L1jIgN1D11ucXefiuJS9UMVP2opoCp2jDKb7wc=
 github.com/marten-seemann/qtls v0.10.0/go.mod h1:UvMd1oaYDACI99/oZUYLzMCkBXQVT0aGm99sJhbT8hs=
 github.com/marten-seemann/qtls-go1-15 v0.1.1/go.mod h1:GyFwywLKkRt+6mfU99csTEY1joMZz5vmB1WNZH3P81I=
@@ -955,6 +971,8 @@ github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJ
 github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
 github.com/modern-go/reflect2 v0.0.0-20180701023420-4b7aa43c6742/go.mod h1:bx2lNnkwVCuqBIxFjflWJWanXIb3RllmbCylyMrvgv0=
 github.com/modern-go/reflect2 v1.0.1/go.mod h1:bx2lNnkwVCuqBIxFjflWJWanXIb3RllmbCylyMrvgv0=
+github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 h1:RWengNIwukTxcDr9M+97sNutRR1RKhG96O6jWumTTnw=
+github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826/go.mod h1:TaXosZuwdSHYgviHp1DAtfrULt5eUgsSMsZf+YrPgl8=
 github.com/mr-tron/base58 v1.1.0/go.mod h1:xcD2VGqlgYjBdcBLw+TuYLr8afG+Hj8g2eTVqeSzSU8=
 github.com/mr-tron/base58 v1.1.1/go.mod h1:xcD2VGqlgYjBdcBLw+TuYLr8afG+Hj8g2eTVqeSzSU8=
 github.com/mr-tron/base58 v1.1.2/go.mod h1:BinMc/sQntlIE1frQmRFPUoPA1Zkr8VRgBdjWI2mNwc=
@@ -1081,6 +1099,8 @@ github.com/pelletier/go-toml v1.2.0/go.mod h1:5z9KED0ma1S8pY6P1sdut58dfprrGBbd/9
 github.com/pelletier/go-toml/v2 v2.1.0 h1:FnwAJ4oYMvbT/34k9zzHuZNrhlz48GB3/s6at6/MHO4=
 github.com/pelletier/go-toml/v2 v2.1.0/go.mod h1:tJU2Z3ZkXwnxa4DPO899bsyIoywizdUvyaeZurnPPDc=
 github.com/performancecopilot/speed v3.0.0+incompatible/go.mod h1:/CLtqpZ5gBg1M9iaPbIdPPGyKcA8hKdoy6hAWba7Yac=
+github.com/perimeterx/marshmallow v1.1.5 h1:a2LALqQ1BlHM8PZblsDdidgv1mWi1DgC2UmX50IvK2s=
+github.com/perimeterx/marshmallow v1.1.5/go.mod h1:dsXbUu8CRzfYP5a87xpp0xq9S3u0Vchtcl8we9tYaXw=
 github.com/pierrec/lz4 v1.0.2-0.20190131084431-473cd7ce01a1/go.mod h1:3/3N9NVKO0jef7pBehbT1qWhCMrIgbYNnFAZCqQ5LRc=
 github.com/pierrec/lz4 v2.0.5+incompatible/go.mod h1:pdkljMzZIN41W+lC3N2tnIh5sFi+IEE17M5jbnwPHcY=
 github.com/pkg/errors v0.8.0/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
@@ -1834,6 +1854,7 @@ gopkg.in/yaml.v2 v2.3.0/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.0/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 grpc.go4.org v0.0.0-20170609214715-11d0a25b4919/go.mod h1:77eQGdRu53HpSqPFJFmuJdjuHRquDANNeA4x7B8WQ9o=

http/handler.go

@@ -11,6 +11,7 @@
 package http
 
 import (
+	"context"
 	"fmt"
 	"net/http"
 	"sync"
@@ -29,12 +30,12 @@ var Version string = "v0"
 var playgroundHandler http.Handler = http.HandlerFunc(http.NotFound)
 
 type Handler struct {
-	db     client.DB
-	router *chi.Mux
-	txs    *sync.Map
+	db  client.DB
+	mux *chi.Mux
+	txs *sync.Map
 }
 
-func NewHandler(db client.DB, opts ServerOptions) *Handler {
+func NewHandler(db client.DB, opts ServerOptions) (*Handler, error) {
 	txs := &sync.Map{}
 
 	tx_handler := &txHandler{}
@@ -44,86 +45,53 @@ func NewHandler(db client.DB, opts ServerOptions) *Handler {
 	lens_handler := &lensHandler{}
 	ccip_handler := &ccipHandler{}
 
-	router := chi.NewRouter()
-	router.Use(middleware.RequestLogger(&logFormatter{}))
-	router.Use(middleware.Recoverer)
-	router.Use(CorsMiddleware(opts))
-	router.Use(ApiMiddleware(db, txs, opts))
-
-	router.Route("/api/"+Version, func(api chi.Router) {
-		api.Use(TransactionMiddleware, StoreMiddleware)
-		api.Route("/tx", func(tx chi.Router) {
-			tx.Post("/", tx_handler.NewTxn)
-			tx.Post("/concurrent", tx_handler.NewConcurrentTxn)
-			tx.Post("/{id}", tx_handler.Commit)
-			tx.Delete("/{id}", tx_handler.Discard)
-		})
-		api.Route("/backup", func(backup chi.Router) {
-			backup.Post("/export", store_handler.BasicExport)
-			backup.Post("/import", store_handler.BasicImport)
-		})
-		api.Route("/schema", func(schema chi.Router) {
-			schema.Post("/", store_handler.AddSchema)
-			schema.Patch("/", store_handler.PatchSchema)
-			schema.Post("/default", store_handler.SetDefaultSchemaVersion)
-		})
-		api.Route("/collections", func(collections chi.Router) {
-			collections.Get("/", store_handler.GetCollection)
-			// with collection middleware
-			collections_tx := collections.With(CollectionMiddleware)
-			collections_tx.Get("/{name}", collection_handler.GetAllDocKeys)
-			collections_tx.Post("/{name}", collection_handler.Create)
-			collections_tx.Patch("/{name}", collection_handler.UpdateWith)
-			collections_tx.Delete("/{name}", collection_handler.DeleteWith)
-			collections_tx.Post("/{name}/indexes", collection_handler.CreateIndex)
-			collections_tx.Get("/{name}/indexes", collection_handler.GetIndexes)
-			collections_tx.Delete("/{name}/indexes/{index}", collection_handler.DropIndex)
-			collections_tx.Get("/{name}/{key}", collection_handler.Get)
-			collections_tx.Patch("/{name}/{key}", collection_handler.Update)
-			collections_tx.Delete("/{name}/{key}", collection_handler.Delete)
-		})
-		api.Route("/lens", func(lens chi.Router) {
-			lens.Use(LensMiddleware)
-			lens.Get("/", lens_handler.Config)
-			lens.Post("/", lens_handler.SetMigration)
-			lens.Post("/reload", lens_handler.ReloadLenses)
-			lens.Get("/{version}", lens_handler.HasMigration)
-			lens.Post("/{version}/up", lens_handler.MigrateUp)
-			lens.Post("/{version}/down", lens_handler.MigrateDown)
-		})
-		api.Route("/graphql", func(graphQL chi.Router) {
-			graphQL.Get("/", store_handler.ExecRequest)
-			graphQL.Post("/", store_handler.ExecRequest)
-		})
-		api.Route("/ccip", func(ccip chi.Router) {
-			ccip.Get("/{sender}/{data}", ccip_handler.ExecCCIP)
-			ccip.Post("/", ccip_handler.ExecCCIP)
-		})
-		api.Route("/p2p", func(p2p chi.Router) {
-			p2p.Get("/info", p2p_handler.PeerInfo)
-			p2p.Route("/replicators", func(p2p_replicators chi.Router) {
-				p2p_replicators.Get("/", p2p_handler.GetAllReplicators)
-				p2p_replicators.Post("/", p2p_handler.SetReplicator)
-				p2p_replicators.Delete("/", p2p_handler.DeleteReplicator)
-			})
-			p2p.Route("/collections", func(p2p_collections chi.Router) {
-				p2p_collections.Get("/", p2p_handler.GetAllP2PCollections)
-				p2p_collections.Post("/", p2p_handler.AddP2PCollection)
-				p2p_collections.Delete("/", p2p_handler.RemoveP2PCollection)
-			})
-		})
-		api.Route("/debug", func(debug chi.Router) {
-			debug.Get("/dump", store_handler.PrintDump)
-		})
+	router, err := NewRouter()
+	if err != nil {
+		return nil, err
+	}
+
+	router.AddMiddleware(
+		ApiMiddleware(db, txs, opts),
+		TransactionMiddleware,
+		StoreMiddleware,
+	)
+
+	tx_handler.bindRoutes(router)
+	store_handler.bindRoutes(router)
+	p2p_handler.bindRoutes(router)
+	ccip_handler.bindRoutes(router)
+
+	router.AddRouteGroup(func(r *Router) {
+		r.AddMiddleware(CollectionMiddleware)
+		collection_handler.bindRoutes(r)
+	})
+
+	router.AddRouteGroup(func(r *Router) {
+		r.AddMiddleware(LensMiddleware)
+		lens_handler.bindRoutes(r)
 	})
 
-	router.Handle("/*", playgroundHandler)
+	if err := router.Validate(context.Background()); err != nil {
+		return nil, err
+	}
+
+	mux := chi.NewMux()
+	mux.Use(
+		middleware.RequestLogger(&logFormatter{}),
+		middleware.Recoverer,
+		CorsMiddleware(opts),
+	)
+	mux.Mount("/api/"+Version, router)
+	mux.Get("/openapi.json", func(rw http.ResponseWriter, req *http.Request) {
+		responseJSON(rw, http.StatusOK, router.OpenAPI())
+	})
+	mux.Handle("/*", playgroundHandler)
 
 	return &Handler{
-		db:     db,
-		router: router,
-		txs:    txs,
-	}
+		db:  db,
+		mux: mux,
+		txs: txs,
+	}, nil
 }
 
 func (h *Handler) Transaction(id uint64) (datastore.Txn, error) {
@@ -135,5 +103,5 @@ func (h *Handler) Transaction(id uint64) (datastore.Txn, error) {
 }
 
 func (h *Handler) ServeHTTP(w http.ResponseWriter, req *http.Request) {
-	h.router.ServeHTTP(w, req)
+	h.mux.ServeHTTP(w, req)
 }

http/handler_ccip.go

@@ -16,6 +16,7 @@ import (
 	"net/http"
 	"strings"
 
+	"github.com/getkin/kin-openapi/openapi3"
 	"github.com/go-chi/chi/v5"
 
 	"github.com/sourcenetwork/defradb/client"
@@ -72,3 +73,52 @@ func (c *ccipHandler) ExecCCIP(rw http.ResponseWriter, req *http.Request) {
 	resultHex := "0x" + hex.EncodeToString(resultJSON)
 	responseJSON(rw, http.StatusOK, CCIPResponse{Data: resultHex})
 }
+
+func (h *ccipHandler) bindRoutes(router *Router) {
+	errorResponse := &openapi3.ResponseRef{
+		Ref: "#/components/responses/error",
+	}
+	ccipRequestSchema := &openapi3.SchemaRef{
+		Ref: "#/components/schemas/ccip_request",
+	}
+	ccipResponseSchema := &openapi3.SchemaRef{
+		Ref: "#/components/schemas/ccip_response",
+	}
+
+	ccipRequest := openapi3.NewRequestBody().
+		WithContent(openapi3.NewContentWithJSONSchemaRef(ccipRequestSchema))
+
+	ccipResponse := openapi3.NewResponse().
+		WithDescription("GraphQL response").
+		WithContent(openapi3.NewContentWithJSONSchemaRef(ccipResponseSchema))
+
+	ccipPost := openapi3.NewOperation()
+	ccipPost.Description = "CCIP POST endpoint"
+	ccipPost.OperationID = "ccip_post"
+	ccipPost.Tags = []string{"ccip"}
+	ccipPost.RequestBody = &openapi3.RequestBodyRef{
+		Value: ccipRequest,
+	}
+	ccipPost.AddResponse(200, ccipResponse)
+	ccipPost.Responses["400"] = errorResponse
+
+	dataPathParam := openapi3.NewPathParameter("data").
+		WithDescription("Hex encoded request data").
+		WithSchema(openapi3.NewStringSchema())
+
+	senderPathParam := openapi3.NewPathParameter("sender").
+		WithDescription("Hex encoded sender address").
+		WithSchema(openapi3.NewStringSchema())
+
+	ccipGet := openapi3.NewOperation()
+	ccipGet.Description = "CCIP GET endpoint"
+	ccipGet.OperationID = "ccip_get"
+	ccipGet.Tags = []string{"ccip"}
+	ccipGet.AddParameter(dataPathParam)
+	ccipGet.AddParameter(senderPathParam)
+	ccipGet.AddResponse(200, ccipResponse)
+	ccipGet.Responses["400"] = errorResponse
+
+	router.AddRoute("/ccip/{sender}/{data}", http.MethodGet, ccipGet, h.ExecCCIP)
+	router.AddRoute("/ccip", http.MethodPost, ccipPost, h.ExecCCIP)
+}