feat: expose runtime OpenAPI contract
Register typed API operations and serve an always-current OpenAPI document without a generation command or committed generated artifact. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Daniel Noulet
parent
314c783659
commit
045f0b7cf2
9 changed files with 533 additions and 76 deletions
48
backend/internal/web/openapi/endpoint_test.go
Normal file
48
backend/internal/web/openapi/endpoint_test.go
Normal file
|
|
@ -0,0 +1,48 @@
|
|||
package openapi_test
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"testing"
|
||||
|
||||
"github.com/danyel/go-guess/backend/internal/web/handler"
|
||||
"github.com/danyel/go-guess/backend/internal/web/router"
|
||||
)
|
||||
|
||||
func TestRuntimeContractContainsRegisteredTypedRoutes(t *testing.T) {
|
||||
api := router.New(
|
||||
handler.New(nil, nil, nil, nil, nil, nil, nil, nil, 10, "http://localhost:5173"),
|
||||
nil,
|
||||
"http://localhost:5173",
|
||||
)
|
||||
response := httptest.NewRecorder()
|
||||
api.ServeHTTP(response, httptest.NewRequest(http.MethodGet, "/api/openapi.json", nil))
|
||||
if response.Code != http.StatusOK {
|
||||
t.Fatalf("expected 200, got %d: %s", response.Code, response.Body.String())
|
||||
}
|
||||
|
||||
var document map[string]any
|
||||
if err := json.NewDecoder(response.Body).Decode(&document); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if document["openapi"] != "3.0.3" {
|
||||
t.Fatalf("unexpected OpenAPI version: %v", document["openapi"])
|
||||
}
|
||||
paths := document["paths"].(map[string]any)
|
||||
if len(paths) < 30 {
|
||||
t.Fatalf("contract contains only %d paths", len(paths))
|
||||
}
|
||||
jobs := paths["/api/jobs"].(map[string]any)
|
||||
createJob := jobs["post"].(map[string]any)
|
||||
if _, ok := createJob["requestBody"]; !ok {
|
||||
t.Fatal("create-job request schema is missing")
|
||||
}
|
||||
if _, ok := createJob["security"]; !ok {
|
||||
t.Fatal("create-job bearer security is missing")
|
||||
}
|
||||
contract := paths["/api/openapi.json"].(map[string]any)["get"].(map[string]any)
|
||||
if parameters := contract["parameters"].([]any); len(parameters) != 0 {
|
||||
t.Fatalf("contract endpoint unexpectedly requires parameters: %#v", parameters)
|
||||
}
|
||||
}
|
||||
243
backend/internal/web/openapi/openapi.go
Normal file
243
backend/internal/web/openapi/openapi.go
Normal file
|
|
@ -0,0 +1,243 @@
|
|||
package openapi
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"net/http"
|
||||
"reflect"
|
||||
"regexp"
|
||||
"sort"
|
||||
"strconv"
|
||||
"strings"
|
||||
"time"
|
||||
)
|
||||
|
||||
type Operation struct {
|
||||
Summary string
|
||||
Request any
|
||||
Response any
|
||||
SuccessStatus int
|
||||
Protected bool
|
||||
RequestContentType string
|
||||
ResponseContentType string
|
||||
QueryParameters []string
|
||||
NoTenant bool
|
||||
}
|
||||
|
||||
type Builder struct {
|
||||
paths map[string]any
|
||||
schemas map[string]any
|
||||
}
|
||||
|
||||
type ParticipantForm struct {
|
||||
FirstName string `json:"firstName"`
|
||||
LastName string `json:"lastName"`
|
||||
Birthday string `json:"birthday,omitempty"`
|
||||
Email string `json:"email"`
|
||||
ContactInfo string `json:"contactInfo"`
|
||||
Photo []byte `json:"photo,omitempty" openapi:"binary"`
|
||||
CV []byte `json:"cv,omitempty" openapi:"binary"`
|
||||
}
|
||||
|
||||
type CVForm struct {
|
||||
CV []byte `json:"cv" openapi:"binary"`
|
||||
}
|
||||
|
||||
func New() *Builder {
|
||||
return &Builder{paths: make(map[string]any), schemas: make(map[string]any)}
|
||||
}
|
||||
|
||||
func (b *Builder) Add(method, path string, operation Operation) {
|
||||
method = strings.ToLower(method)
|
||||
status := operation.SuccessStatus
|
||||
if status == 0 {
|
||||
status = http.StatusOK
|
||||
}
|
||||
contentType := operation.ResponseContentType
|
||||
if contentType == "" {
|
||||
contentType = "application/json"
|
||||
}
|
||||
success := map[string]any{"description": http.StatusText(status)}
|
||||
if operation.Response != nil {
|
||||
responseFormat := ""
|
||||
if contentType == "application/octet-stream" {
|
||||
responseFormat = "binary"
|
||||
}
|
||||
success["content"] = map[string]any{
|
||||
contentType: map[string]any{"schema": b.schema(reflect.TypeOf(operation.Response), responseFormat)},
|
||||
}
|
||||
}
|
||||
responses := map[string]any{
|
||||
strconv.Itoa(status): success,
|
||||
"default": map[string]any{
|
||||
"description": "Error response",
|
||||
"content": map[string]any{
|
||||
"application/json": map[string]any{
|
||||
"schema": b.schema(reflect.TypeOf(errorResponse{}), ""),
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
value := map[string]any{
|
||||
"operationId": operationID(method, path),
|
||||
"summary": operation.Summary,
|
||||
"tags": []string{tagFor(path)},
|
||||
"parameters": b.parameters(path, operation.QueryParameters, !operation.NoTenant),
|
||||
"responses": responses,
|
||||
}
|
||||
if operation.Protected {
|
||||
value["security"] = []map[string][]string{{"bearerAuth": {}}}
|
||||
}
|
||||
if operation.Request != nil {
|
||||
requestContentType := operation.RequestContentType
|
||||
if requestContentType == "" {
|
||||
requestContentType = "application/json"
|
||||
}
|
||||
value["requestBody"] = map[string]any{
|
||||
"required": true,
|
||||
"content": map[string]any{
|
||||
requestContentType: map[string]any{
|
||||
"schema": b.schema(reflect.TypeOf(operation.Request), ""),
|
||||
},
|
||||
},
|
||||
}
|
||||
}
|
||||
pathItem, _ := b.paths[path].(map[string]any)
|
||||
if pathItem == nil {
|
||||
pathItem = make(map[string]any)
|
||||
b.paths[path] = pathItem
|
||||
}
|
||||
pathItem[method] = value
|
||||
}
|
||||
|
||||
func (b *Builder) ServeHTTP(w http.ResponseWriter, _ *http.Request) {
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
_ = json.NewEncoder(w).Encode(b.Document())
|
||||
}
|
||||
|
||||
func (b *Builder) Document() map[string]any {
|
||||
return map[string]any{
|
||||
"openapi": "3.0.3",
|
||||
"info": map[string]any{
|
||||
"title": "Go Guess API",
|
||||
"version": "1.0.0",
|
||||
},
|
||||
"servers": []map[string]string{{"url": "/"}},
|
||||
"paths": b.paths,
|
||||
"components": map[string]any{
|
||||
"securitySchemes": map[string]any{
|
||||
"bearerAuth": map[string]any{"type": "http", "scheme": "bearer", "bearerFormat": "JWT"},
|
||||
},
|
||||
"schemas": b.schemas,
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
func (b *Builder) parameters(path string, queries []string, tenantRequired bool) []map[string]any {
|
||||
result := make([]map[string]any, 0)
|
||||
if tenantRequired {
|
||||
result = append(result, map[string]any{
|
||||
"name": "X-Tenant-Id", "in": "header", "required": true,
|
||||
"schema": map[string]any{"type": "string"},
|
||||
})
|
||||
}
|
||||
for _, match := range regexp.MustCompile(`\{([^}]+)\}`).FindAllStringSubmatch(path, -1) {
|
||||
name := match[1]
|
||||
kind := "integer"
|
||||
if name == "token" {
|
||||
kind = "string"
|
||||
}
|
||||
result = append(result, map[string]any{
|
||||
"name": name, "in": "path", "required": true,
|
||||
"schema": map[string]any{"type": kind},
|
||||
})
|
||||
}
|
||||
for _, name := range queries {
|
||||
result = append(result, map[string]any{
|
||||
"name": name, "in": "query", "required": false,
|
||||
"schema": map[string]any{"type": "string"},
|
||||
})
|
||||
}
|
||||
return result
|
||||
}
|
||||
|
||||
func (b *Builder) schema(value reflect.Type, format string) map[string]any {
|
||||
for value.Kind() == reflect.Pointer {
|
||||
value = value.Elem()
|
||||
}
|
||||
if format == "binary" {
|
||||
return map[string]any{"type": "string", "format": "binary"}
|
||||
}
|
||||
if value == reflect.TypeOf(time.Time{}) {
|
||||
return map[string]any{"type": "string", "format": "date-time"}
|
||||
}
|
||||
switch value.Kind() {
|
||||
case reflect.Struct:
|
||||
name := value.Name()
|
||||
if _, exists := b.schemas[name]; !exists {
|
||||
b.schemas[name] = map[string]any{}
|
||||
properties := make(map[string]any)
|
||||
required := make([]string, 0)
|
||||
for index := range value.NumField() {
|
||||
field := value.Field(index)
|
||||
tag := strings.Split(field.Tag.Get("json"), ",")
|
||||
if tag[0] == "-" || tag[0] == "" {
|
||||
continue
|
||||
}
|
||||
properties[tag[0]] = b.schema(field.Type, field.Tag.Get("openapi"))
|
||||
if !contains(tag[1:], "omitempty") {
|
||||
required = append(required, tag[0])
|
||||
}
|
||||
}
|
||||
sort.Strings(required)
|
||||
component := map[string]any{"type": "object", "properties": properties}
|
||||
if len(required) > 0 {
|
||||
component["required"] = required
|
||||
}
|
||||
b.schemas[name] = component
|
||||
}
|
||||
return map[string]any{"$ref": "#/components/schemas/" + name}
|
||||
case reflect.Slice, reflect.Array:
|
||||
if value.Elem().Kind() == reflect.Uint8 {
|
||||
return map[string]any{"type": "string", "format": "byte"}
|
||||
}
|
||||
return map[string]any{"type": "array", "items": b.schema(value.Elem(), "")}
|
||||
case reflect.Map:
|
||||
return map[string]any{"type": "object", "additionalProperties": b.schema(value.Elem(), "")}
|
||||
case reflect.Bool:
|
||||
return map[string]any{"type": "boolean"}
|
||||
case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64,
|
||||
reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64:
|
||||
return map[string]any{"type": "integer"}
|
||||
case reflect.Float32, reflect.Float64:
|
||||
return map[string]any{"type": "number"}
|
||||
default:
|
||||
return map[string]any{"type": "string"}
|
||||
}
|
||||
}
|
||||
|
||||
type errorResponse struct {
|
||||
Error string `json:"error"`
|
||||
}
|
||||
|
||||
func contains(values []string, expected string) bool {
|
||||
for _, value := range values {
|
||||
if value == expected {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
func operationID(method, path string) string {
|
||||
value := strings.NewReplacer("/", "_", "{", "", "}", "", "-", "_").Replace(path)
|
||||
return method + strings.Trim(value, "_")
|
||||
}
|
||||
|
||||
func tagFor(path string) string {
|
||||
parts := strings.Split(strings.TrimPrefix(path, "/api/"), "/")
|
||||
if len(parts) == 0 || parts[0] == "" {
|
||||
return "system"
|
||||
}
|
||||
return parts[0]
|
||||
}
|
||||
79
backend/internal/web/openapi/openapi_test.go
Normal file
79
backend/internal/web/openapi/openapi_test.go
Normal file
|
|
@ -0,0 +1,79 @@
|
|||
package openapi
|
||||
|
||||
import (
|
||||
"net/http"
|
||||
"testing"
|
||||
)
|
||||
|
||||
type exampleRequest struct {
|
||||
Name string `json:"name"`
|
||||
}
|
||||
|
||||
type exampleResponse struct {
|
||||
ID uint `json:"id"`
|
||||
}
|
||||
|
||||
func TestBuilderCreatesTypedOperationFromRouteRegistration(t *testing.T) {
|
||||
builder := New()
|
||||
builder.Add(http.MethodPost, "/api/examples/{id}", Operation{
|
||||
Summary: "Create an example", Request: exampleRequest{}, Response: exampleResponse{},
|
||||
SuccessStatus: http.StatusCreated, Protected: true,
|
||||
})
|
||||
|
||||
document := builder.Document()
|
||||
paths := document["paths"].(map[string]any)
|
||||
path := paths["/api/examples/{id}"].(map[string]any)
|
||||
operation := path["post"].(map[string]any)
|
||||
if operation["operationId"] != "postapi_examples_id" {
|
||||
t.Fatalf("unexpected operation ID: %v", operation["operationId"])
|
||||
}
|
||||
if _, ok := operation["security"]; !ok {
|
||||
t.Fatal("protected operation does not declare bearer security")
|
||||
}
|
||||
responses := operation["responses"].(map[string]any)
|
||||
if _, ok := responses["201"]; !ok {
|
||||
t.Fatalf("missing 201 response: %#v", responses)
|
||||
}
|
||||
components := document["components"].(map[string]any)
|
||||
schemas := components["schemas"].(map[string]any)
|
||||
if _, ok := schemas["exampleRequest"]; !ok {
|
||||
t.Fatalf("request schema was not generated: %#v", schemas)
|
||||
}
|
||||
if _, ok := schemas["exampleResponse"]; !ok {
|
||||
t.Fatalf("response schema was not generated: %#v", schemas)
|
||||
}
|
||||
}
|
||||
|
||||
func TestBuilderDescribesMultipartBinaryFields(t *testing.T) {
|
||||
builder := New()
|
||||
builder.Add(http.MethodPut, "/api/participants/{id}/cv", Operation{
|
||||
Summary: "Replace a CV", Request: CVForm{}, Response: map[string]string{},
|
||||
RequestContentType: "multipart/form-data",
|
||||
})
|
||||
|
||||
document := builder.Document()
|
||||
components := document["components"].(map[string]any)
|
||||
schemas := components["schemas"].(map[string]any)
|
||||
cv := schemas["CVForm"].(map[string]any)
|
||||
properties := cv["properties"].(map[string]any)
|
||||
field := properties["cv"].(map[string]any)
|
||||
if field["type"] != "string" || field["format"] != "binary" {
|
||||
t.Fatalf("unexpected CV field schema: %#v", field)
|
||||
}
|
||||
}
|
||||
|
||||
func TestBuilderCanExposeSystemOperationsWithoutTenantHeader(t *testing.T) {
|
||||
builder := New()
|
||||
builder.Add(http.MethodGet, "/api/openapi.json", Operation{
|
||||
Summary: "Get contract", Response: map[string]any{}, NoTenant: true,
|
||||
})
|
||||
|
||||
document := builder.Document()
|
||||
paths := document["paths"].(map[string]any)
|
||||
path := paths["/api/openapi.json"].(map[string]any)
|
||||
operation := path["get"].(map[string]any)
|
||||
parameters := operation["parameters"].([]map[string]any)
|
||||
if len(parameters) != 0 {
|
||||
t.Fatalf("system operation unexpectedly requires parameters: %#v", parameters)
|
||||
}
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue