commit 436cb26281397ba20f13cda9825794e08a72a18d
parent 8ea7d55f56548cb5e3c652fb1f435b8efbccd0ea
Author: Yannick Rehberger <yr@ityreh.de>
Date: Thu, 30 Apr 2026 19:16:44 +0200
remove hard swag dependency
Diffstat:
4 files changed, 401 insertions(+), 2 deletions(-)
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,3 @@
.gitignore
**/validation_code
-swagger.json
+doc/swagger.json
diff --git a/Makefile.in b/Makefile.in
@@ -60,6 +60,6 @@ dist:
git archive --format=tar.gz -o taler-directory-${GITVER}.tar.gz --prefix=taler-directory-${GITVER}/ HEAD
openapi:
- swag init -g main.go --dir ./cmd/taldir-server,./pkg/taldir --outputTypes json --output . -v3.1
+ swag init -g main.go --dir ./cmd/taldir-server,./pkg/taldir --outputTypes json --output ./doc -v3.1
.PHONY: all gana server tools check format uninstall install dist openapi
diff --git a/bootstrap b/bootstrap
@@ -12,6 +12,11 @@ if ! existence go; then
exit 1
fi
+if ! existence swag; then
+ echo "WARNING: swag not found in \$PATH. The 'openapi' make target will not work."
+ echo " Install it with: go install github.com/swaggo/swag/cmd/swag@latest"
+fi
+
if [ -d ".git" ]; then
mkdir -p internal/gana
git submodule update --init --recursive
diff --git a/swagger.json b/swagger.json
@@ -0,0 +1,393 @@
+{
+ "components": {
+ "schemas": {
+ "taldir.AliasType": {
+ "properties": {
+ "challenge_fee": {
+ "description": "per challenge fee",
+ "type": "string"
+ },
+ "name": {
+ "description": "Name of the alias type, e.g. \"email\" or \"sms\".",
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "taldir.Entry": {
+ "properties": {
+ "target_uri": {
+ "description": "Target URI to associate with this alias",
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "taldir.ErrorDetail": {
+ "properties": {
+ "code": {
+ "description": "Numeric error code unique to the condition.\nThe other arguments are specific to the error value reported here.",
+ "type": "integer"
+ },
+ "currency": {
+ "description": "Name of the currency than was problematic (if applicable).",
+ "type": "string"
+ },
+ "detail": {
+ "description": "Optional detail about the specific input value that failed. May change without notice!",
+ "type": "string"
+ },
+ "hint": {
+ "description": "Human-readable description of the error, i.e. \"missing parameter\", \"commitment violation\", ...\nShould give a human-readable hint about the error's nature. Optional, may change without notice!",
+ "type": "string"
+ },
+ "index": {
+ "description": "Index of the argument that was bogus (if applicable).",
+ "type": "string"
+ },
+ "object": {
+ "description": "Name of the object that was bogus (if applicable).",
+ "type": "string"
+ },
+ "offset": {
+ "description": "Offset of the argument that was bogus (if applicable).",
+ "type": "string"
+ },
+ "parameter": {
+ "description": "Name of the parameter that was bogus (if applicable).",
+ "type": "string"
+ },
+ "path": {
+ "description": "Path to the argument that was bogus (if applicable).",
+ "type": "string"
+ },
+ "type_actual": {
+ "description": "Type that was provided instead (if applicable).",
+ "type": "string"
+ },
+ "type_expected": {
+ "description": "Expected type (if applicable).",
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "taldir.RateLimitedResponse": {
+ "properties": {
+ "code": {
+ "description": "Taler error code, TALER_EC_TALDIR_REGISTER_RATE_LIMITED.",
+ "type": "integer"
+ },
+ "hint": {
+ "description": "The human readable error message.",
+ "type": "string"
+ },
+ "request_frequency": {
+ "description": "At what frequency are new registrations allowed. FIXME: In what? Currently: In microseconds",
+ "type": "integer"
+ }
+ },
+ "type": "object"
+ },
+ "taldir.RegisterMessage": {
+ "properties": {
+ "alias": {
+ "description": "Alias, in type-specific format",
+ "type": "string"
+ },
+ "duration": {
+ "description": "For how long should the registration last",
+ "type": "integer"
+ },
+ "target_uri": {
+ "description": "Target URI to associate with this alias",
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "taldir.ValidationConfirmation": {
+ "properties": {
+ "solution": {
+ "description": "The solution is the SHA-512 hash of the challenge value\nchosen by TalDir (encoded as string just as given in the URL, but\nexcluding the 0-termination) concatenated with the binary 32-byte\nvalue representing the wallet's EdDSA public key.\nThe hash is provided as string in Crockford base32 encoding.",
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "taldir.VersionResponse": {
+ "properties": {
+ "alias_type": {
+ "description": "Supported alias types",
+ "items": {
+ "$ref": "#/components/schemas/taldir.AliasType"
+ },
+ "type": "array",
+ "uniqueItems": false
+ },
+ "monthly_fee": {
+ "description": "fee for one month of registration",
+ "type": "string"
+ },
+ "name": {
+ "description": "Name of the protocol.",
+ "type": "string"
+ },
+ "version": {
+ "description": "libtool-style representation of the Merchant protocol version, see\nhttps://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning\nThe format is \"current:revision:age\".",
+ "type": "string"
+ }
+ },
+ "type": "object"
+ }
+ }
+ },
+ "info": {
+ "contact": {
+ "url": "https://taler.net"
+ },
+ "description": "The Taler Directory (TalDir) maps alias hashes to wallet URIs. Clients register an alias by completing an out-of-band challenge, then look it up later using the hashed alias.",
+ "license": {
+ "name": "AGPL-3.0-or-later",
+ "url": "https://www.gnu.org/licenses/agpl-3.0.html"
+ },
+ "title": "Taler Directory API",
+ "version": ""
+ },
+ "externalDocs": {
+ "description": "",
+ "url": ""
+ },
+ "paths": {
+ "/config": {
+ "get": {
+ "description": "Returns service metadata including the supported alias types and monthly fee.",
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/taldir.VersionResponse"
+ }
+ }
+ },
+ "description": "OK"
+ }
+ },
+ "summary": "Get service configuration",
+ "tags": [
+ "config"
+ ]
+ }
+ },
+ "/register/{alias_type}": {
+ "post": {
+ "description": "Starts the registration process for an alias. Sends an out-of-band challenge\nvia the specified validator (e.g. email or SMS). If the entry already exists\nwith no changes, returns the remaining validity instead.",
+ "parameters": [
+ {
+ "description": "Alias type (e.g. \\",
+ "in": "path",
+ "name": "alias_type",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "oneOf": [
+ {
+ "type": "object"
+ },
+ {
+ "$ref": "#/components/schemas/taldir.RegisterMessage",
+ "summary": "body",
+ "description": "Registration request"
+ }
+ ]
+ }
+ }
+ },
+ "description": "Registration request",
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "valid_for": {
+ "type": "integer"
+ }
+ },
+ "type": "object"
+ }
+ }
+ },
+ "description": "Existing entry unchanged; returns remaining validity in microseconds"
+ },
+ "202": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object"
+ }
+ }
+ },
+ "description": "Challenge sent"
+ },
+ "400": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/taldir.ErrorDetail"
+ }
+ }
+ },
+ "description": "Invalid request body or target URI"
+ },
+ "402": {
+ "description": "Payment required"
+ },
+ "404": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/taldir.ErrorDetail"
+ }
+ }
+ },
+ "description": "Alias type not supported"
+ },
+ "429": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/taldir.RateLimitedResponse"
+ }
+ }
+ },
+ "description": "Registration rate limit reached"
+ },
+ "500": {
+ "description": "Internal Server Error"
+ }
+ },
+ "summary": "Initiate alias registration",
+ "tags": [
+ "registration"
+ ]
+ }
+ },
+ "/{h_alias}": {
+ "get": {
+ "description": "Returns the target URI associated with the given hashed alias.",
+ "parameters": [
+ {
+ "description": "Crockford base32-encoded SHA-512 hash of the alias",
+ "in": "path",
+ "name": "h_alias",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/taldir.Entry"
+ }
+ }
+ },
+ "description": "OK"
+ },
+ "404": {
+ "description": "Not Found"
+ }
+ },
+ "summary": "Look up an alias entry",
+ "tags": [
+ "entries"
+ ]
+ },
+ "post": {
+ "description": "Submits the solution to the out-of-band challenge to confirm the registration.",
+ "parameters": [
+ {
+ "description": "Crockford base32-encoded SHA-512 hash of the alias",
+ "in": "path",
+ "name": "h_alias",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "oneOf": [
+ {
+ "type": "object"
+ },
+ {
+ "$ref": "#/components/schemas/taldir.ValidationConfirmation",
+ "summary": "body",
+ "description": "Challenge solution"
+ }
+ ]
+ }
+ }
+ },
+ "description": "Challenge solution",
+ "required": true
+ },
+ "responses": {
+ "204": {
+ "description": "Registration confirmed"
+ },
+ "400": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/taldir.ErrorDetail"
+ }
+ }
+ },
+ "description": "Invalid JSON"
+ },
+ "403": {
+ "description": "Wrong solution"
+ },
+ "404": {
+ "description": "Validation not found"
+ },
+ "429": {
+ "description": "Too many solution attempts"
+ },
+ "500": {
+ "description": "Internal Server Error"
+ }
+ },
+ "summary": "Complete alias registration",
+ "tags": [
+ "registration"
+ ]
+ }
+ }
+ },
+ "openapi": "3.1.0",
+ "servers": [
+ {
+ "url": "/"
+ }
+ ]
+}
+\ No newline at end of file
