481 lines
18 KiB
JSON
481 lines
18 KiB
JSON
{
|
|
"openapi": "3.0.3",
|
|
"info": {
|
|
"title": "Password Generator API",
|
|
"version": "2.0.0",
|
|
"description": "Public password generation API and locale metadata for the password generator web app."
|
|
},
|
|
"servers": [
|
|
{
|
|
"url": "http://localhost:8080"
|
|
}
|
|
],
|
|
"paths": {
|
|
"/api/v1/health": {
|
|
"get": {
|
|
"summary": "Health check",
|
|
"description": "Returns the health status of the API service.",
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HealthSuccess"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Error response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/v1/locales/{lang}": {
|
|
"get": {
|
|
"summary": "Fetch locale data",
|
|
"description": "Returns the translation resource for a given locale code.",
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/LocaleSuccess"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "Error response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"parameters": [
|
|
{
|
|
"name": "lang",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"enum": [
|
|
"en",
|
|
"de",
|
|
"de_CH",
|
|
"fr",
|
|
"it",
|
|
"es",
|
|
"pt",
|
|
"ja",
|
|
"zh"
|
|
]
|
|
},
|
|
"description": "Locale code to fetch translation data for."
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/passwords": {
|
|
"get": {
|
|
"summary": "List available password generation types",
|
|
"description": "Returns the supported password generation algorithms.",
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"example": true
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"types": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"timestamp": {
|
|
"type": "string",
|
|
"format": "date-time"
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"example": "Available password generation types"
|
|
}
|
|
},
|
|
"required": [
|
|
"success",
|
|
"data",
|
|
"timestamp"
|
|
]
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Error response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/v1/passwords/generate": {
|
|
"post": {
|
|
"summary": "Generate one or more passwords",
|
|
"description": "Generates passwords using the chosen algorithm and options.",
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/PasswordGenerationSuccess"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Error response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/PasswordGenerationRequest"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/v1/passwords/generators": {
|
|
"get": {
|
|
"summary": "API route",
|
|
"description": "Generated from the public Slim route registry.",
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"additionalProperties": true
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Error response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/v1/passwords/wordlists": {
|
|
"get": {
|
|
"summary": "List available XKCD wordlists",
|
|
"description": "Returns available language wordlists for passphrase generation.",
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/WordlistsSuccess"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Error response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"components": {
|
|
"schemas": {
|
|
"ErrorResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"example": false
|
|
},
|
|
"error": {
|
|
"type": "object",
|
|
"properties": {
|
|
"message": {
|
|
"type": "string",
|
|
"example": "Request failed"
|
|
},
|
|
"code": {
|
|
"type": "string",
|
|
"example": "ERROR"
|
|
},
|
|
"status": {
|
|
"type": "integer",
|
|
"example": 400
|
|
}
|
|
}
|
|
},
|
|
"timestamp": {
|
|
"type": "string",
|
|
"format": "date-time"
|
|
}
|
|
},
|
|
"required": [
|
|
"success",
|
|
"error",
|
|
"timestamp"
|
|
]
|
|
},
|
|
"PasswordGenerationRequest": {
|
|
"type": "object",
|
|
"properties": {
|
|
"type": {
|
|
"type": "string",
|
|
"example": "high-entropy"
|
|
},
|
|
"count": {
|
|
"type": "integer",
|
|
"example": 1
|
|
},
|
|
"options": {
|
|
"type": "object",
|
|
"additionalProperties": true
|
|
}
|
|
}
|
|
},
|
|
"PasswordGenerationSuccess": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"example": true
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"passwords": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"entropy_bits": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"example": 128
|
|
},
|
|
"security_assessment": {
|
|
"type": "string",
|
|
"example": "Strong \u2014 this password has good entropy and is suitable for most uses."
|
|
},
|
|
"raw_technical_details": {
|
|
"type": "object",
|
|
"properties": {
|
|
"entropy_bits": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"example": 77.5
|
|
},
|
|
"generator": {
|
|
"type": "string",
|
|
"example": "XKCD Pass"
|
|
},
|
|
"length": {
|
|
"type": "integer",
|
|
"example": 28
|
|
},
|
|
"security_level": {
|
|
"type": "string",
|
|
"example": "Strong"
|
|
},
|
|
"entropy_breakdown": {
|
|
"type": "object",
|
|
"properties": {
|
|
"entropy_model": {
|
|
"type": "string",
|
|
"example": "xkcd-candidate-space-v1"
|
|
},
|
|
"model_confidence": {
|
|
"type": "string",
|
|
"enum": [
|
|
"high",
|
|
"medium",
|
|
"low"
|
|
]
|
|
},
|
|
"entropy_bits": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"example": 77.5
|
|
}
|
|
},
|
|
"additionalProperties": true
|
|
}
|
|
},
|
|
"additionalProperties": true
|
|
}
|
|
}
|
|
},
|
|
"timestamp": {
|
|
"type": "string",
|
|
"format": "date-time"
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"example": "Generated 1 password(s) of type 'high-entropy'"
|
|
}
|
|
},
|
|
"required": [
|
|
"success",
|
|
"data",
|
|
"timestamp"
|
|
]
|
|
},
|
|
"PasswordTypesSuccess": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"example": true
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"types": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"timestamp": {
|
|
"type": "string",
|
|
"format": "date-time"
|
|
}
|
|
},
|
|
"required": [
|
|
"success",
|
|
"data",
|
|
"timestamp"
|
|
]
|
|
},
|
|
"WordlistsSuccess": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"example": true
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"wordlists": {
|
|
"type": "object",
|
|
"additionalProperties": true
|
|
},
|
|
"count": {
|
|
"type": "integer",
|
|
"example": 2
|
|
}
|
|
}
|
|
},
|
|
"timestamp": {
|
|
"type": "string",
|
|
"format": "date-time"
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"example": "Available wordlists for XKCD password generation"
|
|
}
|
|
},
|
|
"required": [
|
|
"success",
|
|
"data",
|
|
"timestamp"
|
|
]
|
|
},
|
|
"HealthSuccess": {
|
|
"type": "object",
|
|
"properties": {
|
|
"status": {
|
|
"type": "string",
|
|
"example": "healthy"
|
|
},
|
|
"version": {
|
|
"type": "string",
|
|
"example": "2.0.0"
|
|
},
|
|
"timestamp": {
|
|
"type": "string",
|
|
"format": "date-time"
|
|
}
|
|
},
|
|
"required": [
|
|
"status",
|
|
"version",
|
|
"timestamp"
|
|
]
|
|
},
|
|
"LocaleSuccess": {
|
|
"type": "object",
|
|
"additionalProperties": true
|
|
}
|
|
}
|
|
}
|
|
}
|