@unispechq/unispec-schema 0.4.0 → 0.4.2

package/examples/valid/mixed-simple.json

@@ -0,0 +1,56 @@
+{
+	"unispecVersion": "0.1.0",
+	"service": {
+		"name": "mixed-simple-api",
+		"description": "Simple API combining REST and GraphQL protocols",
+		"version": "1.0.0",
+		"baseUrl": "https://api.example.com",
+		"protocols": {
+			"rest": {
+				"routes": [
+					{
+						"name": "getStatus",
+						"summary": "Get API status",
+						"path": "/status",
+						"method": "GET",
+						"responses": {
+							"200": {
+								"description": "Status response",
+								"content": {
+									"application/json": {
+										"schemaRef": "StatusResponse"
+									}
+								}
+							}
+						}
+					}
+				]
+			},
+			"graphql": {
+				"url": "/graphql",
+				"schema": "type Status {\n  status: String!\n  timestamp: String!\n}\n\ntype Query {\n  status: Status!\n}\n",
+				"queries": [
+					{
+						"name": "status",
+						"description": "Get system status",
+						"returnType": "Status!"
+					}
+				]
+			}
+		},
+		"schemas": {
+			"StatusResponse": {
+				"type": "object",
+				"properties": {
+					"status": {
+						"type": "string"
+					},
+					"timestamp": {
+						"type": "string",
+						"format": "date-time"
+					}
+				}
+			}
+		}
+	}
+}

package/examples/valid/rest-complete.json

@@ -0,0 +1,539 @@
+{
+	"unispecVersion": "0.1.0",
+	"service": {
+		"name": "user-management-api",
+		"description": "Complete user management REST API with authentication",
+		"version": "1.0.0",
+		"baseUrl": "https://api.example.com/v1",
+		"contact": {
+			"name": "API Support",
+			"email": "support@example.com",
+			"url": "https://example.com/support"
+		},
+		"license": {
+			"name": "MIT",
+			"url": "https://opensource.org/licenses/MIT"
+		},
+		"tags": ["users", "authentication", "management"],
+		"servers": [
+			{
+				"url": "https://api.example.com/v1",
+				"description": "Production server"
+			},
+			{
+				"url": "https://staging-api.example.com/v1",
+				"description": "Staging server"
+			}
+		],
+		"securitySchemes": {
+			"bearerAuth": {
+				"type": "http",
+				"scheme": "bearer",
+				"bearerFormat": "JWT",
+				"description": "JWT authentication token"
+			},
+			"apiKeyAuth": {
+				"type": "apiKey",
+				"name": "X-API-Key",
+				"in": "header",
+				"description": "API key for authentication"
+			}
+		},
+		"rateLimit": {
+			"requestsPerMinute": 1000,
+			"requestsPerHour": 50000,
+			"perUser": true
+		},
+		"compliance": ["GDPR", "SOC2"],
+		"dataClassification": "confidential",
+		"protocols": {
+			"rest": {
+				"headers": [
+					{
+						"name": "Content-Type",
+						"description": "Request content type",
+						"required": true
+					},
+					{
+						"name": "Accept",
+						"description": "Response content type",
+						"required": true
+					}
+				],
+				"routes": [
+					{
+						"name": "getUsers",
+						"summary": "List all users",
+						"tags": ["users"],
+						"description": "Retrieve a paginated list of users",
+						"path": "/users",
+						"method": "GET",
+						"queryParams": [
+							{
+								"name": "page",
+								"description": "Page number for pagination",
+								"required": false,
+								"schemaRef": "PageNumber"
+							},
+							{
+								"name": "limit",
+								"description": "Number of items per page",
+								"required": false,
+								"schemaRef": "PageSize"
+							},
+							{
+								"name": "search",
+								"description": "Search term for filtering users",
+								"required": false,
+								"schemaRef": "SearchTerm"
+							}
+						],
+						"responses": {
+							"200": {
+								"description": "List of users retrieved successfully",
+								"content": {
+									"application/json": {
+										"schemaRef": "UserListResponse"
+									}
+								}
+							},
+							"400": {
+								"description": "Bad request - invalid parameters",
+								"content": {
+									"application/json": {
+										"schemaRef": "ErrorResponse"
+									}
+								}
+							},
+							"401": {
+								"description": "Unauthorized - authentication required",
+								"content": {
+									"application/json": {
+										"schemaRef": "ErrorResponse"
+									}
+								}
+							}
+						},
+						"security": [
+							{
+								"bearerAuth": []
+							},
+							{
+								"apiKeyAuth": []
+							}
+						]
+					},
+					{
+						"name": "createUser",
+						"summary": "Create a new user",
+						"tags": ["users"],
+						"description": "Create a new user account",
+						"path": "/users",
+						"method": "POST",
+						"requestBody": {
+							"description": "User data for creation",
+							"required": true,
+							"content": {
+								"application/json": {
+									"schemaRef": "CreateUserRequest"
+								}
+							}
+						},
+						"responses": {
+							"201": {
+								"description": "User created successfully",
+								"content": {
+									"application/json": {
+										"schemaRef": "UserResponse"
+									}
+								}
+							},
+							"400": {
+								"description": "Bad request - invalid user data",
+								"content": {
+									"application/json": {
+										"schemaRef": "ErrorResponse"
+									}
+								}
+							},
+							"409": {
+								"description": "Conflict - user already exists",
+								"content": {
+									"application/json": {
+										"schemaRef": "ErrorResponse"
+									}
+								}
+							}
+						},
+						"security": [
+							{
+								"bearerAuth": []
+							}
+						]
+					},
+					{
+						"name": "getUserById",
+						"summary": "Get user by ID",
+						"tags": ["users"],
+						"description": "Retrieve a specific user by their ID",
+						"path": "/users/{id}",
+						"method": "GET",
+						"pathParams": [
+							{
+								"name": "id",
+								"description": "User ID",
+								"required": true,
+								"schemaRef": "UserId"
+							}
+						],
+						"responses": {
+							"200": {
+								"description": "User retrieved successfully",
+								"content": {
+									"application/json": {
+										"schemaRef": "UserResponse"
+									}
+								}
+							},
+							"404": {
+								"description": "User not found",
+								"content": {
+									"application/json": {
+										"schemaRef": "ErrorResponse"
+									}
+								}
+							}
+						},
+						"security": [
+							{
+								"bearerAuth": []
+							},
+							{
+								"apiKeyAuth": []
+							}
+						]
+					},
+					{
+						"name": "updateUser",
+						"summary": "Update user",
+						"tags": ["users"],
+						"description": "Update an existing user's information",
+						"path": "/users/{id}",
+						"method": "PUT",
+						"pathParams": [
+							{
+								"name": "id",
+								"description": "User ID",
+								"required": true,
+								"schemaRef": "UserId"
+							}
+						],
+						"requestBody": {
+							"description": "Updated user data",
+							"required": true,
+							"content": {
+								"application/json": {
+									"schemaRef": "UpdateUserRequest"
+								}
+							}
+						},
+						"responses": {
+							"200": {
+								"description": "User updated successfully",
+								"content": {
+									"application/json": {
+										"schemaRef": "UserResponse"
+									}
+								}
+							},
+							"400": {
+								"description": "Bad request - invalid user data",
+								"content": {
+									"application/json": {
+										"schemaRef": "ErrorResponse"
+									}
+								}
+							},
+							"404": {
+								"description": "User not found",
+								"content": {
+									"application/json": {
+										"schemaRef": "ErrorResponse"
+									}
+								}
+							}
+						},
+						"security": [
+							{
+								"bearerAuth": []
+							}
+						]
+					},
+					{
+						"name": "deleteUser",
+						"summary": "Delete user",
+						"tags": ["users"],
+						"description": "Delete a user account",
+						"path": "/users/{id}",
+						"method": "DELETE",
+						"pathParams": [
+							{
+								"name": "id",
+								"description": "User ID",
+								"required": true,
+								"schemaRef": "UserId"
+							}
+						],
+						"responses": {
+							"204": {
+								"description": "User deleted successfully"
+							},
+							"404": {
+								"description": "User not found",
+								"content": {
+									"application/json": {
+										"schemaRef": "ErrorResponse"
+									}
+								}
+							}
+						},
+						"security": [
+							{
+								"bearerAuth": []
+							}
+						]
+					},
+					{
+						"name": "authenticateUser",
+						"summary": "User authentication",
+						"tags": ["authentication"],
+						"description": "Authenticate user and return JWT token",
+						"path": "/auth/login",
+						"method": "POST",
+						"requestBody": {
+							"description": "User credentials",
+							"required": true,
+							"content": {
+								"application/json": {
+									"schemaRef": "LoginRequest"
+								}
+							}
+						},
+						"responses": {
+							"200": {
+								"description": "Authentication successful",
+								"content": {
+									"application/json": {
+										"schemaRef": "AuthResponse"
+									}
+								}
+							},
+							"401": {
+								"description": "Invalid credentials",
+								"content": {
+									"application/json": {
+										"schemaRef": "ErrorResponse"
+									}
+								}
+							}
+						},
+						"security": []
+					}
+				]
+			}
+		},
+		"schemas": {
+			"UserId": {
+				"type": "string",
+				"pattern": "^[0-9a-fA-F]{24}$",
+				"description": "MongoDB ObjectId string"
+			},
+			"PageNumber": {
+				"type": "integer",
+				"minimum": 1,
+				"default": 1,
+				"description": "Page number for pagination"
+			},
+			"PageSize": {
+				"type": "integer",
+				"minimum": 1,
+				"maximum": 100,
+				"default": 20,
+				"description": "Number of items per page"
+			},
+			"SearchTerm": {
+				"type": "string",
+				"minLength": 1,
+				"maxLength": 100,
+				"description": "Search term for filtering"
+			},
+			"CreateUserRequest": {
+				"type": "object",
+				"required": ["email", "password", "firstName", "lastName"],
+				"properties": {
+					"email": {
+						"type": "string",
+						"format": "email",
+						"description": "User email address"
+					},
+					"password": {
+						"type": "string",
+						"minLength": 8,
+						"description": "User password (min 8 characters)"
+					},
+					"firstName": {
+						"type": "string",
+						"minLength": 1,
+						"maxLength": 50,
+						"description": "User first name"
+					},
+					"lastName": {
+						"type": "string",
+						"minLength": 1,
+						"maxLength": 50,
+						"description": "User last name"
+					},
+					"phone": {
+						"type": "string",
+						"description": "Optional phone number"
+					}
+				}
+			},
+			"UpdateUserRequest": {
+				"type": "object",
+				"properties": {
+					"firstName": {
+						"type": "string",
+						"minLength": 1,
+						"maxLength": 50,
+						"description": "User first name"
+					},
+					"lastName": {
+						"type": "string",
+						"minLength": 1,
+						"maxLength": 50,
+						"description": "User last name"
+					},
+					"phone": {
+						"type": "string",
+						"description": "Optional phone number"
+					},
+					"email": {
+						"type": "string",
+						"format": "email",
+						"description": "User email address"
+					}
+				}
+			},
+			"LoginRequest": {
+				"type": "object",
+				"required": ["email", "password"],
+				"properties": {
+					"email": {
+						"type": "string",
+						"format": "email",
+						"description": "User email address"
+					},
+					"password": {
+						"type": "string",
+						"description": "User password"
+					}
+				}
+			},
+			"UserResponse": {
+				"type": "object",
+				"properties": {
+					"id": {
+						"$ref": "#/service/schemas/UserId"
+					},
+					"email": {
+						"type": "string",
+						"format": "email"
+					},
+					"firstName": {
+						"type": "string"
+					},
+					"lastName": {
+						"type": "string"
+					},
+					"phone": {
+						"type": "string"
+					},
+					"createdAt": {
+						"type": "string",
+						"format": "date-time"
+					},
+					"updatedAt": {
+						"type": "string",
+						"format": "date-time"
+					}
+				}
+			},
+			"UserListResponse": {
+				"type": "object",
+				"properties": {
+					"users": {
+						"type": "array",
+						"items": {
+							"$ref": "#/service/schemas/UserResponse"
+						}
+					},
+					"pagination": {
+						"type": "object",
+						"properties": {
+							"page": {
+								"$ref": "#/service/schemas/PageNumber"
+							},
+							"limit": {
+								"$ref": "#/service/schemas/PageSize"
+							},
+							"total": {
+								"type": "integer",
+								"minimum": 0,
+								"description": "Total number of users"
+							},
+							"totalPages": {
+								"type": "integer",
+								"minimum": 0,
+								"description": "Total number of pages"
+							}
+						}
+					}
+				}
+			},
+			"AuthResponse": {
+				"type": "object",
+				"properties": {
+					"token": {
+						"type": "string",
+						"description": "JWT authentication token"
+					},
+					"expiresIn": {
+						"type": "integer",
+						"description": "Token expiration time in seconds"
+					},
+					"user": {
+						"$ref": "#/service/schemas/UserResponse"
+					}
+				}
+			},
+			"ErrorResponse": {
+				"type": "object",
+				"properties": {
+					"error": {
+						"type": "string",
+						"description": "Error code"
+					},
+					"message": {
+						"type": "string",
+						"description": "Human-readable error message"
+					},
+					"details": {
+						"type": "object",
+						"description": "Additional error details"
+					}
+				}
+			}
+		}
+	}
+}