fixup a few errors in our OpenAPI spec for REST endpoints (#342)

Signed-off-by: Sarah Funkhouser <[email protected]>

internal/httpserve/handlers/acccountrolesorganization.go

@@ -104,7 +104,25 @@ func (h *Handler) BindAccountRolesOrganization() *openapi3.Operation {
 		},
 	}
 
-	h.AddRequestBody("AccountRolesOrganizationRequest", models.ExampleAccountRolesOrganizationRequest, orgRoles)
+	orgRoles.AddResponse(http.StatusInternalServerError, internalServerError())
+	orgRoles.AddResponse(http.StatusBadRequest, badRequest())
+	orgRoles.AddResponse(http.StatusUnauthorized, unauthorized())
+
+	return orgRoles
+}
+
+// BindAccountRolesOrganization returns the OpenAPI3 operation for accepting an account roles organization request
+func (h *Handler) BindAccountRolesOrganizationByID() *openapi3.Operation {
+	orgRoles := openapi3.NewOperation()
+	orgRoles.Description = "List roles a subject has in relation to the organization ID provided"
+	orgRoles.OperationID = "AccountRolesOrganizationByID"
+	orgRoles.Security = &openapi3.SecurityRequirements{
+		openapi3.SecurityRequirement{
+			"bearer": []string{},
+		},
+	}
+
+	h.AddPathParameter("AccountRolesOrganizationRequest", "id", models.ExampleAccountRolesOrganizationRequest, orgRoles)
 	h.AddResponse("AccountRolesOrganizationReply", "success", models.ExampleAccountRolesOrganizationReply, orgRoles, http.StatusOK)
 	orgRoles.AddResponse(http.StatusInternalServerError, internalServerError())
 	orgRoles.AddResponse(http.StatusBadRequest, badRequest())

internal/httpserve/handlers/openapi.go

@@ -58,6 +58,24 @@ func (h *Handler) AddRequestBody(name string, body interface{}, op *openapi3.Ope
 	request.Content.Get(httpsling.ContentTypeJSON).Examples["success"] = &openapi3.ExampleRef{Value: openapi3.NewExample(body)}
 }
 
+// AddQueryParameter is used to add a query parameter definition to the OpenAPI schema (e.g ?name=value)
+func (h *Handler) AddQueryParameter(name string, paramName string, body interface{}, op *openapi3.Operation) {
+	schemaRef := &openapi3.SchemaRef{Ref: "#/components/schemas/" + name}
+	param := openapi3.NewQueryParameter(paramName)
+
+	param.Schema = schemaRef
+	op.AddParameter(param)
+}
+
+// AddPathParameter is used to add a path parameter definition to the OpenAPI schema (e.g. /users/{id})
+func (h *Handler) AddPathParameter(name string, paramName string, body interface{}, op *openapi3.Operation) {
+	schemaRef := &openapi3.SchemaRef{Ref: "#/components/schemas/" + name}
+	param := openapi3.NewPathParameter(paramName)
+
+	param.Schema = schemaRef
+	op.AddParameter(param)
+}
+
 // AddResponse is used to add a response definition to the OpenAPI schema
 func (h *Handler) AddResponse(name string, description string, body interface{}, op *openapi3.Operation, status int) {
 	response := openapi3.NewResponse().

internal/httpserve/handlers/verifyemail.go

@@ -152,7 +152,7 @@ func (h *Handler) BindVerifyEmailHandler() *openapi3.Operation {
 	verify.OperationID = "VerifyEmail"
 	verify.Security = &openapi3.SecurityRequirements{}
 
-	h.AddRequestBody("VerifyRequest", models.ExampleVerifySuccessRequest, verify)
+	h.AddQueryParameter("VerifyRequest", "token", models.ExampleVerifySuccessRequest, verify)
 	h.AddResponse("VerifyReply", "success", models.ExampleVerifySuccessResponse, verify, http.StatusOK)
 	verify.AddResponse(http.StatusInternalServerError, internalServerError())
 	verify.AddResponse(http.StatusBadRequest, badRequest())

internal/httpserve/handlers/verifysubscribe.go

@@ -155,7 +155,7 @@ func (h *Handler) BindVerifySubscriberHandler() *openapi3.Operation {
 	verify.OperationID = "VerifySubscriberEmail"
 	verify.Security = &openapi3.SecurityRequirements{}
 
-	h.AddRequestBody("VerifySubscriptionRequest", models.ExampleVerifySubscriptionSuccessRequest, verify)
+	h.AddQueryParameter("VerifySubscriptionRequest", "token", models.ExampleVerifySubscriptionSuccessRequest, verify)
 	h.AddResponse("VerifySubscriptionReply", "success", models.ExampleVerifySubscriptionResponse, verify, http.StatusOK)
 	verify.AddResponse(http.StatusInternalServerError, internalServerError())
 	verify.AddResponse(http.StatusBadRequest, badRequest())

internal/httpserve/route/accountrolesorganization.go

@@ -30,9 +30,12 @@ func registerAccountRolesOrganizationHandler(router *Router) (err error) {
 	}
 
 	// add an additional route with the path param
-	route.Path = "/account/roles/organization/:id"
+	route.Path = "/account/roles/organization/:{id}"
+	route.Name = name + "ByID"
 
-	if err := router.Addv1Route(route.Path, route.Method, rolesOrganizationOperation, route); err != nil {
+	rolesOrganizationOperationByID := router.Handler.BindAccountRolesOrganizationByID()
+
+	if err := router.Addv1Route(route.Path, route.Method, rolesOrganizationOperationByID, route); err != nil {
 		return err
 	}
 

internal/httpserve/server/openapi.go

@@ -29,7 +29,7 @@ func NewOpenAPISpec() (*openapi3.T, error) {
 	}
 
 	errorResponse := &openapi3.SchemaRef{
-		Ref: "#/components/schemas/ErrorResponse",
+		Ref: "#/components/schemas/ErrorReply",
 	}
 
 	_, err := openapi3gen.NewSchemaRefForValue(&rout.StatusError{}, schemas)
@@ -71,7 +71,6 @@ func NewOpenAPISpec() (*openapi3.T, error) {
 		Value: openapi3.NewSecurityScheme().
 			WithType("http").
 			WithScheme("bearer").
-			WithIn("header").
 			WithDescription("Bearer authentication, the token must be a valid API token"),
 	}
 
@@ -93,19 +92,6 @@ func NewOpenAPISpec() (*openapi3.T, error) {
 		}).Scheme(),
 	}
 
-	securityschemes["apikey"] = &openapi3.SecuritySchemeRef{
-		Value: (*APIKey)(&APIKey{
-			Name: "X-API-Key",
-		}).Scheme(),
-	}
-
-	securityschemes["basic"] = &openapi3.SecuritySchemeRef{
-		Value: (*Basic)(&Basic{
-			Username: "username",
-			Password: "password",
-		}).Scheme(),
-	}
-
 	return &openapi3.T{
 		OpenAPI: "3.1.0",
 		Info: &openapi3.Info{