docs: add health check to swagger and resolve swagger issues (ory#488)

Closes ory#355

client/handler.go

@@ -367,7 +367,7 @@ func (h *Handler) Get(w http.ResponseWriter, r *http.Request, ps httprouter.Para
 //       oauth2: hydra.clients
 //
 //     Responses:
-//       204
+//       204: emptyResponse
 //       401: genericError
 //       403: genericError
 //       500: genericError

cmd/server/handler.go

@@ -129,10 +129,7 @@ func (h *Handler) registerRoutes(router *httprouter.Router) {
 		Manager: ctx.GroupManager,
 	}
 	h.Groups.SetRoutes(router)
-
-	router.GET("/health", func(rw http.ResponseWriter, r *http.Request, _ httprouter.Params) {
-		rw.WriteHeader(http.StatusNoContent)
-	})
+	_ = newHealthHandler(c, router)
 
 	// Create root account if new install
 	createRS256KeysIfNotExist(c, oauth2.ConsentEndpointKey, "private", "sig")

cmd/server/handler_health_factory.go

@@ -0,0 +1,13 @@
+package server
+
+import (
+	"github.com/julienschmidt/httprouter"
+	"github.com/ory/hydra/config"
+	"github.com/ory/hydra/health"
+)
+
+func newHealthHandler(c *config.Config, router *httprouter.Router) *health.Handler {
+	h := &health.Handler{}
+	h.SetRoutes(router)
+	return h
+}

doc.go

@@ -27,13 +27,26 @@
 //         type: oauth2
 //         authorizationUrl: /oauth2/auth
 //         tokenUrl: /oauth2/token
-//         in: header
 //         flow: accessCode
-//
 //     Extensions:
 //     ---
 //     x-request-id: string
+//     x-forwarded-proto: string
 //     ---
 //
 // swagger:meta
 package main
+
+
+//         scopes:
+//           hydra.clients: "A scope required to manage OAuth 2.0 Clients"
+//           hydra.policies: "A scope required to manage access control policies"
+//           hydra.groups: "A scope required to manage warden groups"
+//           hydra.warden: "A scope required to make access control inquiries"
+//           hydra.keys.get: "A scope required to fetch JSON Web Keys"
+//           hydra.keys.create: "A scope required to create JSON Web Keys"
+//           hydra.keys.delete: "A scope required to delete JSON Web Keys"
+//           hydra.keys.update: "A scope required to get JSON Web Keys"
+//           offline: "A scope required when requesting refresh tokens"
+//           openid: "Request an OpenID Connect ID Token"
+//

doc_swagger.go

@@ -18,3 +18,9 @@ type genericError struct {
 		Message string `json:"message"`
 	}
 }
+
+// The standard error format
+// swagger:response emptyResponse
+type emptyResponse struct {
+	Description string `json:"description,omitempty"`
+}