feat: Add OpenAPI/Swagger documentation

- Install swaggo dependencies for Swagger/OpenAPI generation
- Add comprehensive API annotations to all endpoints
- Refactor API handlers into named functions for better documentation
- Extract ActionEntity and EvaluationResponseContext as named types
- Add Swagger UI endpoint at /swagger/index.html
- Generate OpenAPI 2.0 specification (swagger.yaml, swagger.json)
- Add Makefile targets for swagger generation
- Document all endpoints: /health, /ready, /status, /info, /authzen/decision, /metrics
- Add API metadata: title, description, contact, license, tags

OpenAPI spec available at docs/swagger/
Swagger UI accessible at http://localhost:6001/swagger/index.html

Addresses Phase 4 Task #1: OpenAPI/Swagger documentation

Co-authored-by: GitHub Copilot

Author: leifj

.github/workflows/go.yml

@@ -136,8 +136,8 @@ jobs:
 
         echo "Files in .badges/main before copy:"
         ls -la .badges/main/ || echo "Directory doesn't exist"
-        
-        # Copy the generated badge files from temp  
+
+        # Copy the generated badge files from temp
         mkdir -p .badges/main
         cp -v /tmp/badges/*.svg .badges/main/
         echo "Badges copied to badges branch:"

Makefile

@@ -59,9 +59,20 @@ test-all: test test-integration ## run all tests including integration tests
 build: check-go-version ## build the library
 	CGO_ENABLED=1 go build ${LDFLAGS} -trimpath -o gt -a ./cmd/main.go
 
+.PHONY: swagger
+swagger: install-swag ## Generate OpenAPI/Swagger documentation
+	$(GOBIN)/swag init -g main.go --output docs/swagger --parseDependency --parseInternal 2>&1 | grep -v "warning: failed to evaluate" || true
+	@echo "Swagger documentation generated at docs/swagger/"
+	@echo "View at: http://localhost:6001/swagger/index.html (when server is running)"
+
+.PHONY: install-swag
+install-swag: ## Install swag tool for generating Swagger docs
+	@which swag > /dev/null || (echo "Installing swag..." && go install github.com/swaggo/swag/cmd/swag@latest)
+
 .PHONY: clean
 clean: ## remove temporary files
 	go clean
+	rm -rf docs/swagger
 
 .PHONY: deps
 deps: ## Update dependencies

README.md

@@ -22,7 +22,7 @@
 
 Go-Trust is a local trust engine that provides trust decisions based on ETSI TS 119612 Trust Status Lists (TSLs). It allows clients to abstract trust decisions through an AuthZEN policy decision point (PDP). The service evaluates trust in subjects identified by X509 certificates using a set of TSLs.
 
-Go-Trust is not meant to be used cross trust boundaries. The reason for creating Go-Trust is to promote interoperability across implementations that rely on ETSI trust status lists such as the EUDI wallet. ETSI TS 119 612 is complex to implement correctly and hopefully Go-Trust provides a way to both ensure correct trust evaluation as well as provide performance enhancements by allowing for local caching etc. Go-Trust is an API service meant to be run inside the same trust domain as the entity that relies on trust evaluation (for instance a wallet unit or an issuer).
+Go-Trust is not meant to be used across trust boundaries. The reason for creating Go-Trust is to promote interoperability across implementations that rely on ETSI trust status lists such as the EUDI wallet. ETSI TS 119 612 is complex to implement correctly and hopefully Go-Trust provides a way to both ensure correct trust evaluation as well as provide performance enhancements by allowing for local caching etc. Go-Trust is an API service meant to be run inside the same trust domain as the entity that relies on trust evaluation (for instance a wallet unit or an issuer).
 
 Go-Trust can also be used to maintain and publish ETSI trust status lists, act as a local distribution point and provide policy based transformation of trust status lists.