Swagger documentation

.gitignore

@@ -1,6 +1,6 @@
 *.osm
 *.pbf
-*.json
+!*.json
 *.geojson
 map.osm
 map.csv
@@ -18,4 +18,9 @@ cmd/horizon/horizon
 cmd/horizon/horizon.exe
 cmd/horizon/*.zip
 cmd/horizon/*.tar.gz
-.build.sh
+.build.sh
+.swag-gen.sh
+docs/*
+rest/docs/docs.go
+rest/docs/swagger.json
+rest/docs/swagger.yaml

README.md

@@ -1,4 +1,4 @@
-# Horizon v0.5.0 [![GoDoc](https://godoc.org/github.com/LdDl/horizon?status.svg)](https://godoc.org/github.com/LdDl/horizon) [![Build Status](https://travis-ci.com/LdDl/horizon.svg?branch=master)](https://travis-ci.com/LdDl/horizon) [![Sourcegraph](https://sourcegraph.com/github.com/LdDl/horizon/-/badge.svg)](https://sourcegraph.com/github.com/LdDl/horizon?badge) [![Go Report Card](https://goreportcard.com/badge/github.com/LdDl/horizon)](https://goreportcard.com/report/github.com/LdDl/horizon) [![GitHub tag](https://img.shields.io/github/tag/LdDl/horizon.svg)](https://github.com/LdDl/horizon/releases)
+# Horizon v0.5.1 [![GoDoc](https://godoc.org/github.com/LdDl/horizon?status.svg)](https://godoc.org/github.com/LdDl/horizon) [![Build Status](https://travis-ci.com/LdDl/horizon.svg?branch=master)](https://travis-ci.com/LdDl/horizon) [![Sourcegraph](https://sourcegraph.com/github.com/LdDl/horizon/-/badge.svg)](https://sourcegraph.com/github.com/LdDl/horizon?badge) [![Go Report Card](https://goreportcard.com/badge/github.com/LdDl/horizon)](https://goreportcard.com/report/github.com/LdDl/horizon) [![GitHub tag](https://img.shields.io/github/tag/LdDl/horizon.svg)](https://github.com/LdDl/horizon/releases)
 
 # Work in progress
 Horizon is project aimed to do map matching (snap GPS data to map) and routing (find shortest path between two points)
@@ -22,12 +22,12 @@ Horizon is targeted to make map matching as [OSRM](https://github.com/Project-OS
 Via _go get_:
 ```shell
 go get github.com/LdDl/horizon
-go install github.com/LdDl/horizon/cmd/horizon@v0.5.0
+go install github.com/LdDl/horizon/cmd/horizon@v0.5.1
 ```
 
 Via downloading prebuilt binary and making updates in yours PATH environment varibale (both Linux and Windows):
-* Windows - https://github.com/LdDl/horizon/releases/download/v0.5.0/windows-horizon.zip
-* Linux - https://github.com/LdDl/horizon/releases/download/v0.5.0/linux-amd64-horizon.tar.gz
+* Windows - https://github.com/LdDl/horizon/releases/download/v0.5.1/windows-horizon.zip
+* Linux - https://github.com/LdDl/horizon/releases/download/v0.5.1/linux-amd64-horizon.tar.gz
 
 Check if **horizon** binary was installed properly:
 ```shell
@@ -120,6 +120,12 @@ Instruction has been made for Linux mainly. For Windows or OSX the way may vary.
     <img src="images/pic1.png" width="720">
     <img src="images/pic2.png" width="720">
 
+7. There is also [Swagger](https://en.wikipedia.org/wiki/Swagger_(software)) documentation for inialized REST API.
+
+    If you use http://localhost:32800/ then you can navigate to http://localhost:32800/api/v0.1.0/docs#overview for API documentation. It may look like (thanks [rapidoc](https://github.com/mrin9/RapiDoc#rapidoc)):
+
+    <img src="images/swagger1.png" width="720">
+
 ## Benchmark
 Please follow [link](BENCHMARK.md)
 
@@ -147,6 +153,7 @@ Thanks for approach described in this paper:
 * Fiber framework (used for server app) - [Fiber](https://github.com/gofiber/fiber). License is MIT
 * MapboxGL for Front-end - [mapboxgl](https://github.com/mapbox/mapbox-gl-js). License is 3-Clause BSD license
 * moments.js for Front-end - [moment.js](https://github.com/moment/moment/). License is MIT
+* rapidoc for [swagger](https://en.wikipedia.org/wiki/Swagger_(software)) visualization - [rapidoc](https://github.com/mrin9/RapiDoc/blob/master/LICENSE.txt). License is MIT
 
 ## License
 You can check it [here](https://github.com/LdDl/horizon/blob/master/LICENSE)

ROADMAP.md

@@ -20,6 +20,7 @@ New ideas, thought about needed features will be store in this file.
 * More screenshots in README
 * Migrate to Fiber v2
 * Migrate to new version of CH (https://github.com/LdDl/ch) v1.7.5
+* Swagger docs (autogen) - https://github.com/LdDl/horizon/pull/10
 
 ### W.I.P
 * gRPC server side
@@ -28,8 +29,6 @@ New ideas, thought about needed features will be store in this file.
     * Isochrones service
     * gRPC docs (autogen)
 
-* Swagger docs (autogen) - https://github.com/LdDl/horizon/pull/10
-
 * Snake case for JSON's
 
 * Stabilization of core (need many tests as possible)

cmd/horizon/main.go

@@ -8,6 +8,7 @@ import (
 
 	"github.com/LdDl/horizon"
 	"github.com/LdDl/horizon/rest"
+	"github.com/LdDl/horizon/rest/docs"
 	"github.com/gofiber/fiber/v2"
 	"github.com/gofiber/fiber/v2/middleware/cors"
 	"github.com/valyala/fasthttp"
@@ -26,6 +27,16 @@ var (
 	apiVersion = "0.1.0"
 )
 
+// @title API for working with Horizon
+// @version 0.1.0
+
+// @contact.name API support
+// @contact.url https://github.com/LdDl/horizon#table-of-contents
+// @contact.email sexykdi@gmail.com
+
+// @BasePath /
+
+// @schemes http https
 func main() {
 	flag.Parse()
 
@@ -43,7 +54,7 @@ func main() {
 	config := fiber.Config{
 		DisableStartupMessage: false,
 		ErrorHandler: func(ctx *fiber.Ctx, err error) error {
-			log.Println(err)
+			log.Println("error:", err)
 			return ctx.Status(fasthttp.StatusInternalServerError).JSON(map[string]string{"Error": "undefined"})
 		},
 		IdleTimeout: 10 * time.Second,
@@ -68,6 +79,12 @@ func main() {
 	apiVersionGroup.Post("/shortest", rest.FindSP(matcher))
 	apiVersionGroup.Post("/isochrones", rest.FindIsochrones(matcher))
 
+	docsStaticGroup := apiVersionGroup.Group("/docs-static")
+	docsStaticGroup.Use("/", docs.PrepareStaticAssets())
+
+	docsGroup := apiVersionGroup.Group("/docs")
+	docsGroup.Use("/", docs.PrepareStaticPage())
+
 	// Start server
 	if err := server.Listen(fmt.Sprintf("%s:%d", *addrFlag, *portFlag)); err != nil {
 		fmt.Println(err)

errors.go

@@ -13,4 +13,5 @@ var (
 	ErrTargetNotFound         = fmt.Errorf("can't find closest edge for 'target' point")
 	ErrTargetHasMoreEdges     = fmt.Errorf("more than 1 edge for 'target' point")
 	ErrPathNotFound           = fmt.Errorf("path not found")
+	ErrSameVertex             = fmt.Errorf("same vertex")
 )

go.mod

@@ -1,6 +1,6 @@
 module github.com/LdDl/horizon
 
-go 1.13
+go 1.16
 
 require (
 	github.com/LdDl/ch v1.7.7

map_matcher_simple_sp.go

@@ -67,6 +67,9 @@ func (matcher *MapMatcher) FindShortestPath(source, target *GPSMeasurement, stat
 	if ans == -1.0 {
 		return MatcherResult{}, ErrPathNotFound
 	}
+	if len(path) < 2 {
+		return MatcherResult{}, ErrSameVertex
+	}
 	edges := []Edge{}
 	result := MatcherResult{
 		Observations: make([]*ObservationResult, 2),

rest/codes/codes.go

@@ -0,0 +1,78 @@
+package codes
+
+// Success200 OK
+// swagger:model
+type Success200 struct {
+	// Code text
+	Status string `json:"Status" example:"OK"`
+}
+
+// Success201 Created
+// swagger:model
+type Success201 struct {
+	// Code text
+	Status string `json:"Status" example:"Created"`
+}
+
+// Error500 Internal Server Error
+// swagger:model
+type Error500 struct {
+	// Error text
+	Error string `json:"Error" example:"Internal Server Error"`
+}
+
+// Error502 Bad Gateway
+// swagger:model
+type Error502 struct {
+	// Error text
+	Error string `json:"Error" example:"Bad Gateway"`
+}
+
+// Error503 Service Unavailable
+// swagger:model
+type Error503 struct {
+	// Error text
+	Error string `json:"Error" example:"Service Unavailable"`
+}
+
+// Error400 Internal Server Error
+// swagger:model
+type Error400 struct {
+	// Error text
+	Error string `json:"Error" example:"Internal Server Error"`
+}
+
+// Error401 Unauthorized
+// swagger:model
+type Error401 struct {
+	// Error text
+	Error string `json:"Error" example:"Unauthorized"`
+}
+
+// Error403 Forbidden
+// swagger:model
+type Error403 struct {
+	// Error text
+	Error string `json:"Error" example:"Forbidden"`
+}
+
+// Error409 Conflict
+// swagger:model
+type Error409 struct {
+	// Error text
+	Error string `json:"Error" example:"Conflict"`
+}
+
+// Error424 Failed Dependency
+// swagger:model
+type Error424 struct {
+	// Error text
+	Error string `json:"Error" example:"Failed Dependency"`
+}
+
+// Error422 Unprocessable Entity
+// swagger:model
+type Error422 struct {
+	// Error text
+	Error string `json:"Error" example:"Unprocessable Entity"`
+}