📑 use swagger for documentation

Makefile

@@ -0,0 +1,5 @@
+install:
+	which swagger || GO111MODULE=off go get -u github.com/go-swagger/go-swagger/cmd/swagger
+
+swagger: install
+	GO111MODULE=off swagger generate spec -o ./swagger.yaml --scan-models

products/handlers/get.go

@@ -0,0 +1,27 @@
+package handlers
+
+import (
+	"fmt"
+	"net/http"
+
+	"github.com/rjNemo/go-micro/products/data"
+)
+
+// swagger:route GET /products products listProducts
+// Returns a list of products
+// responses:
+// 	200: productsResponse
+
+// GetProducts writes all products to response in JSON format
+func (p *Products) GetProducts(w http.ResponseWriter, r *http.Request) {
+	p.logger.Println("Handle 'GET' request")
+	// fetch products from the datastore
+	productList := data.AllProducts()
+	// serialize list to JSON
+	err := productList.ToJSON(w)
+	if err != nil {
+		errMsg := fmt.Sprintf("Unable to encode request: %s\n", err)
+		http.Error(w, errMsg, http.StatusInternalServerError)
+		return
+	}
+}

products/handlers/products.go

@@ -1,3 +1,17 @@
+// Package classification Product API
+//
+// Documentation for Product API
+//
+// Schemes: http
+// BasePath: /
+// Version: 1.0.0
+//
+// Consumes:
+// 	- application/json
+//
+// Produces:
+// 	- application/json
+// swagger:meta
 package handlers
 
 import (
@@ -17,25 +31,19 @@ type Products struct {
 	logger *log.Logger
 }
 
+// list of products in the response. For go-swagger
+// swagger:response productsResponse
+type productsResponse struct {
+	// All products in the datastore
+	// in: body
+	Body []models.Product
+}
+
 // New creates a Products handler
 func New(logger *log.Logger) *Products {
 	return &Products{logger: logger}
 }
 
-// GetProducts writes all products to response in JSON format
-func (p *Products) GetProducts(w http.ResponseWriter, r *http.Request) {
-	p.logger.Println("Handle 'GET' request")
-	// fetch products from the datastore
-	productList := data.AllProducts()
-	// serialize list to JSON
-	err := productList.ToJSON(w)
-	if err != nil {
-		errMsg := fmt.Sprintf("Unable to encode request: %s\n", err)
-		http.Error(w, errMsg, http.StatusInternalServerError)
-		return
-	}
-}
-
 // AddProduct reads request body and creates new product
 func (p *Products) AddProduct(w http.ResponseWriter, r *http.Request) {
 	p.logger.Println("Handle 'POST' request")
@@ -101,18 +109,3 @@ func (p *Products) ProductValidationMiddleware(next http.Handler) http.Handler {
 		next.ServeHTTP(w, req)
 	})
 }
-
-// RegisterRoutes associates path to controller
-func (p *Products) RegisterRoutes(r *mux.Router) {
-	// GET
-	getRouter := r.Methods(http.MethodGet).Subrouter()
-	getRouter.HandleFunc("/", p.GetProducts)
-	// POST
-	postRouter := r.Methods(http.MethodPost).Subrouter()
-	postRouter.HandleFunc("/", p.AddProduct)
-	postRouter.Use(p.ProductValidationMiddleware)
-	// PUT
-	putRouter := r.Methods(http.MethodPut).Subrouter()
-	putRouter.HandleFunc("/{id:[0-9]+}", p.UpdateProduct)
-	putRouter.Use(p.ProductValidationMiddleware)
-}

products/handlers/routes.go

@@ -0,0 +1,22 @@
+package handlers
+
+import (
+	"net/http"
+
+	"github.com/gorilla/mux"
+)
+
+// RegisterRoutes associates path to controller
+func (p *Products) RegisterRoutes(r *mux.Router) {
+	// GET
+	getRouter := r.Methods(http.MethodGet).Subrouter()
+	getRouter.HandleFunc("/", p.GetProducts)
+	// POST
+	postRouter := r.Methods(http.MethodPost).Subrouter()
+	postRouter.HandleFunc("/", p.AddProduct)
+	postRouter.Use(p.ProductValidationMiddleware)
+	// PUT
+	putRouter := r.Methods(http.MethodPut).Subrouter()
+	putRouter.HandleFunc("/{id:[0-9]+}", p.UpdateProduct)
+	putRouter.Use(p.ProductValidationMiddleware)
+}

swagger.yaml

@@ -0,0 +1,52 @@
+basePath: /
+consumes:
+- application/json
+definitions:
+  Product:
+    description: Product defines the structure of a product
+    properties:
+      description:
+        type: string
+        x-go-name: Description
+      id:
+        format: int64
+        type: integer
+        x-go-name: ID
+      name:
+        type: string
+        x-go-name: Name
+      price:
+        format: float
+        type: number
+        x-go-name: Price
+      sku:
+        type: string
+        x-go-name: SKU
+    type: object
+    x-go-package: github.com/rjNemo/go-micro/products/models
+info:
+  description: Documentation for Product API
+  title: Product API
+  version: 1.0.0
+paths:
+  /products:
+    get:
+      description: Returns a list of products
+      operationId: listProducts
+      responses:
+        "200":
+          $ref: '#/responses/productsResponse'
+      tags:
+      - products
+produces:
+- application/json
+responses:
+  productsResponse:
+    description: list of products in the response. For go-swagger
+    schema:
+      items:
+        $ref: '#/definitions/Product'
+      type: array
+schemes:
+- http
+swagger: "2.0"