From ffc618f0558fa3e8fe151f70b188cb253b892170 Mon Sep 17 00:00:00 2001
From: Andres Uribe <auribe@tbd.email>
Date: Thu, 30 Mar 2023 17:47:46 -0400
Subject: [PATCH] Moarrr docs (#363)

* Added health docs

* Added readiness check.

* Some docs.

* Update credential.go
---
 pkg/server/router/credential.go    |  9 +++++++--
 pkg/server/router/health.go        |  1 +
 pkg/server/router/readiness.go     | 13 ++++++++-----
 pkg/service/framework/framework.go |  7 +++++--
 4 files changed, 21 insertions(+), 9 deletions(-)

diff --git a/pkg/server/router/credential.go b/pkg/server/router/credential.go
index 9420b39eb..9a2d6fbec 100644
--- a/pkg/server/router/credential.go
+++ b/pkg/server/router/credential.go
@@ -82,8 +82,12 @@ func (c CreateCredentialRequest) ToServiceRequest() credential.CreateCredentialR
 }
 
 type CreateCredentialResponse struct {
-	Credential    *credsdk.VerifiableCredential `json:"credential,omitempty"`
-	CredentialJWT *keyaccess.JWT                `json:"credentialJwt,omitempty"`
+	// A verifiable credential conformant to the media type `application/vc+ld+json`.
+	Credential *credsdk.VerifiableCredential `json:"credential,omitempty"`
+
+	// The same verifiable credential, but using the syntax defined for the media type `application/vc+jwt`. See
+	// https://w3c.github.io/vc-jwt/ for more details.
+	CredentialJWT *keyaccess.JWT `json:"credentialJwt,omitempty"`
 }
 
 // CreateCredential godoc
@@ -392,6 +396,7 @@ func (cr CredentialRouter) VerifyCredential(ctx context.Context, w http.Response
 }
 
 type GetCredentialsResponse struct {
+	// Array of credential containers.
 	Credentials []credmodel.Container `json:"credentials"`
 }
 
diff --git a/pkg/server/router/health.go b/pkg/server/router/health.go
index d5eb318bd..f09d9f40d 100644
--- a/pkg/server/router/health.go
+++ b/pkg/server/router/health.go
@@ -8,6 +8,7 @@ import (
 )
 
 type GetHealthCheckResponse struct {
+	// Status is always equal to `OK`.
 	Status string `json:"status"`
 }
 
diff --git a/pkg/server/router/readiness.go b/pkg/server/router/readiness.go
index 8d01d5ecf..b85601caf 100644
--- a/pkg/server/router/readiness.go
+++ b/pkg/server/router/readiness.go
@@ -20,19 +20,22 @@ type readiness struct {
 }
 
 type GetReadinessResponse struct {
-	Status          svcframework.Status                       `json:"status"`
+	// Overall status of the ssi service.
+	Status svcframework.Status `json:"status"`
+
+	// A map from the name of the service ot the status of that current service.
 	ServiceStatuses map[svcframework.Type]svcframework.Status `json:"serviceStatuses"`
 }
 
 // Readiness godoc
 //
 // @Summary     Readiness
-// @Description ready runs a number of application specific checks to see if all the
-// @Description relied upon service are healthy. Should return a 500 if not ready.
+// @Description Readiness runs a number of application specific checks to see if all the relied upon services are
+// @Description healthy.
 // @Tags        Readiness
 // @Accept      json
 // @Produce     json
-// @Success     200 {string} string "OK"
+// @Success     200 {object} GetReadinessResponse
 // @Router      /readiness [get]
 func (r readiness) ready(ctx context.Context, w http.ResponseWriter, _ *http.Request) error {
 	services := r.getter.getServices()
@@ -56,7 +59,7 @@ func (r readiness) ready(ctx context.Context, w http.ResponseWriter, _ *http.Req
 	} else {
 		status = svcframework.Status{
 			Status:  svcframework.StatusReady,
-			Message: "all service ready",
+			Message: "all services ready",
 		}
 	}
 	response := GetReadinessResponse{
diff --git a/pkg/service/framework/framework.go b/pkg/service/framework/framework.go
index 644899de7..ec19a486b 100644
--- a/pkg/service/framework/framework.go
+++ b/pkg/service/framework/framework.go
@@ -28,8 +28,11 @@ func (t Type) String() string {
 
 // Status is for service reporting on their status
 type Status struct {
-	Status  StatusState `json:"status,omitempty"`
-	Message string      `json:"message,omitempty"`
+	// Either `ready` or `not_ready`.
+	Status StatusState `json:"status,omitempty"`
+
+	// When `status` is `not_ready`, then message contains explanation of why it's not ready.
+	Message string `json:"message,omitempty"`
 }
 
 func (s Status) IsReady() bool {