YouTip

The following is=A complete Swagger document example is a detailed specification for a user management system API.\n\nThis document describes a user management system API, including basic user information, authentication services, data models, and more.\n\nThe API follows RESTful style and uses JSON format for data exchange.\n\nWe can use Swagger Editor to test your document online, online address: [https://editor.swagger.io/](https://editor.swagger.io/). Simply copy and paste your YAML or JSON into the editor, and the right panel will display the visual API documentation.\n\n!(#)\n\n## Example\n\nopenapi: 3.0.0\n\n info:\n\n title: My First API\n\n description:|\n\n This is a simple API example document that demonstrates the basic functionality of a user management system.\n\n Includes user query, create, update, and delete operations.\n\n version: 1.0.0\n\n contact:\n\n name: API Support Team\n\n email: support@example.com\n\n url: https://www.example.com/support\n\n license:\n\n name: Apache 2.0\n\n url: https://www.apache.org/licenses/LICENSE-2.0.html\n\nservers:\n\n- url: https://api.example.com/v1\n\n description: Production environment\n\n- url: https://staging-api.example.com/v1\n\n description: Staging environment\n\n- url: https://dev-api.example.com/v1\n\n description: Development environment\n\ntags:\n\n- name: User\n\n description: User management related operations\n\n- name: Auth\n\n description: Authentication related operations\n\npaths:\n\n/users:\n\nget:\n\n tags:\n\n- User\n\n summary: Get all users list\n\n description: Returns all user information in the system, supports pagination and filtering\n\n operationId: getUsers\n\n parameters:\n\n- name: limit\n\nin: query\n\n description: Maximum number of results to return\n\n required:false\n\n schema:\n\n type: integer\n\n format: int32\n\n minimum:1\n\n maximum:100\n\ndefault:20\n\n- name: offset\n\nin: query\n\n description: Pagination offset\n\n required:false\n\n schema:\n\n type: integer\n\n format: int32\n\n minimum:0\n\ndefault:0\n\n- name: status\n\nin: query\n\n description: Filter by user status\n\n required:false\n\n schema:\n\n type: string\n\nenum:[active, inactive, banned]\n\n responses:\n\n'200':\n\n description: Successfully retrieved user list\n\n content:\n\n application/json:\n\n schema:\n\n type: object\n\n properties:\n\n total:\n\n type: integer\n\n description: Total number of users\n\n users:\n\n type: array\n\n items:\n\n $ref:'#/components/schemas/User'\n\n example:\n\n total:2\n\n users:\n\n- id:1\n\n username:"john_doe"\n\n email:"john@example.com"\n\n status:"active"\n\n createdAt:"2023-05-01T12:00:00Z"\n\n- id:2\n\n username:"jane_smith"\n\n email:"jane@example.com"\n\n status:"active"\n\n createdAt:"2023-05-02T14:30:00Z"\n\n'400':\n\n description: Invalid request\n\n content:\n\n application/json:\n\n schema:\n\n $ref:'#/components/schemas/Error'\n\n'401':\n\n $ref:'#/components/responses/UnauthorizedError'\n\n security:\n\n- bearerAuth:[]\n\npost:\n\n tags:\n\n- User\n\n summary: Create new user\n\n description: Create a new user in the system\n\n operationId: createUser\n\n requestBody:\n\n description: User information\n\n required:true\n\n content:\n\n application/json:\n\n schema:\n\n $ref:'#/components/schemas/NewUser'\n\n example:\n\n username:"new_user"\n\n email:"new_user@example.com"\n\n password:"securePassword123"\n\n responses:\n\n'201':\n\n description: User created successfully\n\n content:\n\n application/json:\n\n schema:\n\n $ref:'#/components/schemas/User'\n\n example:\n\n id:3\n\n username:"new_user"\n\n email:"new_user@example.com"\n\n status:"active"\n\n createdAt:"2023-05-10T09:15:00Z"\n\n'400':\n\n description: Invalid request\n\n content:\n\n application/json:\n\n schema:\n\n $ref:'#/components/schemas/Error'\n\n example:\n\n code:400\n\n message:"Invalid email format"\n\n'409':\n\n description: Resource conflict\n\n content:\n\n application/json:\n\n schema:\n\n $ref:'#/components/schemas/Error'\n\n example:\n\n code:409\n\n message:"Username already exists"\n\n'401':\n\n $ref:'#/components/responses/UnauthorizedError'\n\n security:\n\n- bearerAuth:[]\n\n/users/{userId}:\n\n parameters:\n\n- name: userId\n\nin: path\n\n description: User ID\n\n required:true\n\n schema:\n\n type: integer\n\n format: int64\n\nget:\n\n tags:\n\n- User\n\n summary: Get specific user\n\n description: Get detailed information for a specific user by ID\n\n operationId: getUserById\n\n responses:\n\n'200':\n\n description: Successfully retrieved user information\n\n content:\n\n application/json:\n\n schema:\n\n $ref:'#/components/schemas/UserDetail'\n\n example:\n\n id:1\n\n username:"john_doe"\n\n email:"john@example.com"\n\n firstName:"John"\n\n lastName:"Doe"\n\n phone:"+1234567890"\n\n status:"active"\n\n createdAt:"2023-05-01T12:00:00Z"\n\n lastLogin:"2023-05-10T08:30:00Z"\n\n'404':\n\n description: User not found\n\n content:\n\n application/json:\n\n schema:\n\n $ref:'#/components/schemas/Error'\n\n example:\n\n code:404\n\n message:"User not found"\n\n'401':\n\n $ref:'#/components/responses/UnauthorizedError'\n\n security:\n\n- bearerAuth:[]\n\nput:\n\n tags:\n\n- User\n\n summary: Update user information\n\n description: Update information for a specific user\n\n operationId: updateUser\n\n requestBody:\n\n description: Updated user information\n\n required:true\n\n content:\n\n application/json:\n\n schema:\n\n $ref:'#/components/schemas/UpdateUser'\n\n example:\n\n firstName:"Jonathan"\n\n lastName:"Doe"\n\n phone:"+1987654321"\n\n responses:\n\n'200':\n\n description: User information updated successfully\n\n content:\n\n application/json:\n\n schema:\n\n $ref:'#/components/schemas/UserDetail'\n\n'400':\n\n description: Invalid request\n\n content:\n\n application/json:\n\n schema:\n\n $ref:'#/components/schemas/Error'\n\n'404':\n\n description: User not found\n\n content:\n\n application/json:\n\n schema:\n\n $ref:'#/components/schemas/Error'\n\n'401':\n\n $ref:'#/components/responses/UnauthorizedError'\n\n security:\n\n- bearerAuth:[]\n\ndelete:\n\n tags:\n\n- User\n\n summary: Delete user\n\n description: Delete a specific user from the system\n\n operationId: deleteUser\n\n responses:\n\n'204':\n\n description: User deleted successfully