236 lines
6.0 KiB
YAML
236 lines
6.0 KiB
YAML
# OpenAPI 3.0.3 specification for example API
|
|
openapi: 3.0.3
|
|
|
|
# API information
|
|
info:
|
|
title: Example API
|
|
version: 1.0.0
|
|
description: This is a sample API definition for demonstration purposes.
|
|
termsOfService: https://www.example.com/terms/
|
|
contact:
|
|
name: API Support
|
|
url: https://www.example.com/support
|
|
email: support@example.com
|
|
license:
|
|
name: MIT
|
|
url: https://opensource.org/licenses/MIT
|
|
|
|
# Server URLs
|
|
servers:
|
|
- url: https://api.example.com/v1
|
|
description: Production server
|
|
- url: https://staging.api.example.com/v1
|
|
description: Staging server
|
|
|
|
# Paths (API endpoints)
|
|
paths:
|
|
/users:
|
|
get:
|
|
summary: Get all users
|
|
description: Returns a list of all users.
|
|
operationId: getUsers
|
|
tags:
|
|
- Users
|
|
responses:
|
|
'200':
|
|
description: Successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/User'
|
|
'500':
|
|
description: Internal server error
|
|
post:
|
|
summary: Create a new user
|
|
description: Creates a new user with the provided information.
|
|
operationId: createUser
|
|
tags:
|
|
- Users
|
|
requestBody:
|
|
description: User object to be created
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/UserCreate'
|
|
responses:
|
|
'201':
|
|
description: User created successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/User'
|
|
'400':
|
|
description: Invalid input
|
|
'500':
|
|
description: Internal server error
|
|
|
|
/users/{userId}:
|
|
get:
|
|
summary: Get a user by ID
|
|
description: Returns a single user based on the provided ID.
|
|
operationId: getUserById
|
|
tags:
|
|
- Users
|
|
parameters:
|
|
- name: userId
|
|
in: path
|
|
description: ID of the user to retrieve
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
format: int64
|
|
responses:
|
|
'200':
|
|
description: Successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/User'
|
|
'404':
|
|
description: User not found
|
|
'500':
|
|
description: Internal server error
|
|
put:
|
|
summary: Update a user by ID
|
|
description: Updates an existing user with the provided information.
|
|
operationId: updateUser
|
|
tags:
|
|
- Users
|
|
parameters:
|
|
- name: userId
|
|
in: path
|
|
description: ID of the user to update
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
format: int64
|
|
requestBody:
|
|
description: User object to be updated
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/UserUpdate'
|
|
responses:
|
|
'200':
|
|
description: User updated successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/User'
|
|
'400':
|
|
description: Invalid input
|
|
'404':
|
|
description: User not found
|
|
'500':
|
|
description: Internal server error
|
|
delete:
|
|
summary: Delete a user by ID
|
|
description: Deletes a user based on the provided ID.
|
|
operationId: deleteUser
|
|
tags:
|
|
- Users
|
|
parameters:
|
|
- name: userId
|
|
in: path
|
|
description: ID of the user to delete
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
format: int64
|
|
responses:
|
|
'204':
|
|
description: User deleted successfully (no content)
|
|
'404':
|
|
description: User not found
|
|
'500':
|
|
description: Internal server error
|
|
|
|
# Components (reusable schemas, parameters, etc.)
|
|
components:
|
|
schemas:
|
|
User:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
format: int64
|
|
description: Unique identifier for the user
|
|
username:
|
|
type: string
|
|
description: User's username
|
|
email:
|
|
type: string
|
|
format: email
|
|
description: User's email address
|
|
firstName:
|
|
type: string
|
|
description: User's first name
|
|
lastName:
|
|
type: string
|
|
description: User's last name
|
|
createdAt:
|
|
type: string
|
|
format: date-time
|
|
description: Date and time the user was created
|
|
required:
|
|
- id
|
|
- username
|
|
- email
|
|
UserCreate:
|
|
type: object
|
|
properties:
|
|
username:
|
|
type: string
|
|
description: User's username
|
|
email:
|
|
type: string
|
|
format: email
|
|
description: User's email address
|
|
firstName:
|
|
type: string
|
|
description: User's first name
|
|
lastName:
|
|
type: string
|
|
description: User's last name
|
|
password:
|
|
type: string
|
|
description: User's password (REPLACE_ME - consider security best practices)
|
|
required:
|
|
- username
|
|
- email
|
|
- password
|
|
UserUpdate:
|
|
type: object
|
|
properties:
|
|
username:
|
|
type: string
|
|
description: User's username
|
|
email:
|
|
type: string
|
|
format: email
|
|
description: User's email address
|
|
firstName:
|
|
type: string
|
|
description: User's first name
|
|
lastName:
|
|
type: string
|
|
description: User's last name
|
|
|
|
securitySchemes:
|
|
bearerAuth: # Define a security scheme for JWT authentication
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
|
|
# Security requirements for the API
|
|
security:
|
|
- bearerAuth: [] # Apply the JWT authentication scheme globally
|
|
|
|
# Tags (for grouping operations)
|
|
tags:
|
|
- name: Users
|
|
description: Operations related to users |