From 21d3899105c854b59cfa20cc0eabf6178bac3304 Mon Sep 17 00:00:00 2001 From: Sarah Funkhouser <147884153+golanglemonade@users.noreply.github.com> Date: Fri, 20 Dec 2024 12:49:26 -0700 Subject: [PATCH] fixup a few errors in our OpenAPI spec for REST endpoints (#342) Signed-off-by: Sarah Funkhouser <147884153+golanglemonade@users.noreply.github.com> --- .../handlers/acccountrolesorganization.go | 20 ++++++++++++++++++- internal/httpserve/handlers/openapi.go | 18 +++++++++++++++++ internal/httpserve/handlers/verifyemail.go | 2 +- .../httpserve/handlers/verifysubscribe.go | 2 +- .../route/accountrolesorganization.go | 7 +++++-- internal/httpserve/server/openapi.go | 16 +-------------- 6 files changed, 45 insertions(+), 20 deletions(-) diff --git a/internal/httpserve/handlers/acccountrolesorganization.go b/internal/httpserve/handlers/acccountrolesorganization.go index b77e264e..c03baa8e 100644 --- a/internal/httpserve/handlers/acccountrolesorganization.go +++ b/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()) diff --git a/internal/httpserve/handlers/openapi.go b/internal/httpserve/handlers/openapi.go index a477c06b..d403c9db 100644 --- a/internal/httpserve/handlers/openapi.go +++ b/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(). diff --git a/internal/httpserve/handlers/verifyemail.go b/internal/httpserve/handlers/verifyemail.go index d4e56f93..9d2621f5 100644 --- a/internal/httpserve/handlers/verifyemail.go +++ b/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()) diff --git a/internal/httpserve/handlers/verifysubscribe.go b/internal/httpserve/handlers/verifysubscribe.go index 0bfc77cb..5916940f 100644 --- a/internal/httpserve/handlers/verifysubscribe.go +++ b/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()) diff --git a/internal/httpserve/route/accountrolesorganization.go b/internal/httpserve/route/accountrolesorganization.go index d59f45cb..576d94b6 100644 --- a/internal/httpserve/route/accountrolesorganization.go +++ b/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 } diff --git a/internal/httpserve/server/openapi.go b/internal/httpserve/server/openapi.go index 8af8c9da..8931e747 100644 --- a/internal/httpserve/server/openapi.go +++ b/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{