Elysia Tools

在一个清晰的工作台里浏览工具、案例、可视化和主题指南。

热门分类

专题

语言
ZHDERUPTENFRES

Elysia Tools

导航

API 文档

OpenAPI/Swagger 示例

OpenAPI/Swagger 规范示例,用于 REST API 文档和契约定义

案例

这个案例集合中的条目

代码yaml简单

基础 OpenAPI 3.0 宠物商店 API

简单的宠物商店管理系统的 OpenAPI 3.0 规范

标签

openapi, petstore, rest, api

yaml
openapi: 3.0.0
info:
  title: Pet Store API
  description: A simple pet store management API
  version: 1.0.0
  contact:
    name: API Support
    email: support@petstore.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.petstore.com/v1
    description: Production server
  - url: https://staging-api.petstore.com/v1
    description: Staging server

paths:
  /pets:
    get:
      summary: List all pets
      description: Returns a list of all pets in the store
      parameters:
        - name: limit
          in: query
          description: Maximum number of pets to return
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
        - name: status
          in: query
          description: Filter by pet status
          required: false
          schema:
            type: string
            enum: [available, pending, sold]
      responses:
        '200':
          description: A list of pets
          content:
            application/json:
              schema:
                type: object
                properties:
                  pets:
                    type: array
                    items:
                      $ref: '#/components/schemas/Pet'
                  total:
                    type: integer
                    example: 42
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'

    post:
      summary: Add a new pet to the store
      description: Creates a new pet in the store
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewPet'
      responses:
        '201':
          description: Pet created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /pets/{petId}:
    get:
      summary: Get pet by ID
      description: Returns a single pet by its ID
      parameters:
        - name: petId
          in: path
          required: true
          description: ID of the pet to retrieve
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

    put:
      summary: Update an existing pet
      description: Updates pet information
      parameters:
        - name: petId
          in: path
          required: true
          description: ID of the pet to update
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewPet'
      responses:
        '200':
          description: Pet updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/BadRequest'

    delete:
      summary: Delete a pet
      description: Deletes a pet from the store
      parameters:
        - name: petId
          in: path
          required: true
          description: ID of the pet to delete
          schema:
            type: integer
            format: int64
      responses:
        '204':
          description: Pet deleted successfully
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

components:
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
        - status
      properties:
        id:
          type: integer
          format: int64
          example: 123
          readOnly: true
        name:
          type: string
          example: "Buddy"
          minLength: 1
          maxLength: 100
        category:
          $ref: '#/components/schemas/Category'
        status:
          type: string
          enum: [available, pending, sold]
          example: "available"
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
        photoUrls:
          type: array
          items:
            type: string
            format: uri
          example: ["https://example.com/photos/123.jpg"]

    NewPet:
      type: object
      required:
        - name
        - status
      properties:
        name:
          type: string
          example: "Buddy"
          minLength: 1
          maxLength: 100
        category:
          $ref: '#/components/schemas/Category'
        status:
          type: string
          enum: [available, pending, sold]
          example: "available"
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
        photoUrls:
          type: array
          items:
            type: string
            format: uri

    Category:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        name:
          type: string
          example: "Dogs"
          maxLength: 50

    Tag:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        name:
          type: string
          example: "friendly"
          maxLength: 50

    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
          example: "Validation failed"

  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication

security:
  - ApiKeyAuth: []
代码yaml中等

用户管理 API(含认证)

完整的用户管理 API,包含认证、授权和基于角色的访问控制

标签

openapi, authentication, user-management, jwt, roles

yaml
openapi: 3.0.1
info:
  title: User Management API
  description: API for managing users, roles, and permissions
  version: 2.1.0
  contact:
    name: Developer Team
    email: dev@company.com
    url: https://company.com/contact
  termsOfService: https://company.com/terms
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0

servers:
  - url: https://api.company.com/v2
    description: Production server
  - url: https://staging-api.company.com/v2
    description: Staging server
  - url: https://dev-api.company.com/v2
    description: Development server

tags:
  - name: users
    description: Operations about users
  - name: auth
    description: Authentication operations
  - name: roles
    description: Role management operations

paths:
  /auth/login:
    post:
      tags:
        - auth
      summary: User login
      description: Authenticates a user and returns access tokens
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
            examples:
              user_login:
                summary: User login
                value:
                  email: "user@example.com"
                  password: "securePassword123"
              admin_login:
                summary: Admin login
                value:
                  email: "admin@company.com"
                  password: "adminPassword123"
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
              examples:
                user_response:
                  summary: User token response
                  value:
                    accessToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
                    refreshToken: "def50200f8b75b3a85b78e2686e6df8..."
                    expiresIn: 3600
                    tokenType: "Bearer"
                    user:
                      id: 123
                      email: "user@example.com"
                      roles: ["user"]
        '401':
          $ref: '#/components/responses/Unauthorized'
        '400':
          $ref: '#/components/responses/ValidationError'

  /auth/refresh:
    post:
      tags:
        - auth
      summary: Refresh access token
      description: Uses refresh token to generate new access token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefreshTokenRequest'
      responses:
        '200':
          description: Token refreshed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /users:
    get:
      tags:
        - users
      summary: List users
      description: Returns a paginated list of users
      security:
        - bearerAuth: []
      parameters:
        - name: page
          in: query
          description: Page number
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          description: Number of users per page
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: search
          in: query
          description: Search term for users
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 100
        - name: role
          in: query
          description: Filter by role
          required: false
          schema:
            type: string
            enum: [user, admin, moderator]
        - name: status
          in: query
          description: Filter by status
          required: false
          schema:
            type: string
            enum: [active, inactive, suspended]
      responses:
        '200':
          description: Users retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

    post:
      tags:
        - users
      summary: Create user
      description: Creates a new user account
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/Conflict'

  /users/{userId}:
    get:
      tags:
        - users
      summary: Get user by ID
      description: Returns detailed information about a specific user
      security:
        - bearerAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          description: User ID
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: User retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'

    put:
      tags:
        - users
      summary: Update user
      description: Updates user information
      security:
        - bearerAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          description: User ID
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserRequest'
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'

    delete:
      tags:
        - users
      summary: Delete user
      description: Deletes a user account
      security:
        - bearerAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          description: User ID
          schema:
            type: integer
            format: int64
      responses:
        '204':
          description: User deleted successfully
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /users/{userId}/roles:
    get:
      tags:
        - users
      summary: Get user roles
      description: Returns all roles assigned to a user
      security:
        - bearerAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          description: User ID
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: User roles retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserRolesResponse'

components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
        - firstName
        - lastName
        - status
        - createdAt
      properties:
        id:
          type: integer
          format: int64
          example: 123
          readOnly: true
        email:
          type: string
          format: email
          example: "user@example.com"
          maxLength: 255
        firstName:
          type: string
          example: "John"
          minLength: 1
          maxLength: 100
        lastName:
          type: string
          example: "Doe"
          minLength: 1
          maxLength: 100
        avatar:
          type: string
          format: uri
          example: "https://example.com/avatars/123.jpg"
          nullable: true
        status:
          type: string
          enum: [active, inactive, suspended]
          example: "active"
        roles:
          type: array
          items:
            $ref: '#/components/schemas/Role'
          example:
            - id: 1
              name: "user"
        lastLoginAt:
          type: string
          format: date-time
          nullable: true
          example: "2025-11-30T10:30:00Z"
        createdAt:
          type: string
          format: date-time
          readOnly: true
          example: "2025-01-15T09:00:00Z"
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          example: "2025-11-29T14:20:00Z"

    CreateUserRequest:
      type: object
      required:
        - email
        - firstName
        - lastName
        - password
      properties:
        email:
          type: string
          format: email
          example: "newuser@example.com"
          maxLength: 255
        firstName:
          type: string
          example: "Jane"
          minLength: 1
          maxLength: 100
        lastName:
          type: string
          example: "Smith"
          minLength: 1
          maxLength: 100
        password:
          type: string
          format: password
          example: "securePassword123"
          minLength: 8
          maxLength: 128
        roleIds:
          type: array
          items:
            type: integer
            format: int64
          example: [1]
          default: [1]

    UpdateUserRequest:
      type: object
      properties:
        firstName:
          type: string
          example: "Jane"
          minLength: 1
          maxLength: 100
        lastName:
          type: string
          example: "Smith"
          minLength: 1
          maxLength: 100
        avatar:
          type: string
          format: uri
          example: "https://example.com/avatars/456.jpg"
          nullable: true
        status:
          type: string
          enum: [active, inactive, suspended]
          example: "active"

    LoginRequest:
      type: object
      required:
        - email
        - password
      properties:
        email:
          type: string
          format: email
          example: "user@example.com"
        password:
          type: string
          format: password
          example: "securePassword123"

    LoginResponse:
      type: object
      required:
        - accessToken
        - refreshToken
        - expiresIn
        - tokenType
        - user
      properties:
        accessToken:
          type: string
          example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
        refreshToken:
          type: string
          example: "def50200f8b75b3a85b78e2686e6df8..."
        expiresIn:
          type: integer
          example: 3600
        tokenType:
          type: string
          example: "Bearer"
        user:
          $ref: '#/components/schemas/User'

    TokenResponse:
      type: object
      required:
        - accessToken
        - expiresIn
        - tokenType
      properties:
        accessToken:
          type: string
          example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
        expiresIn:
          type: integer
          example: 3600
        tokenType:
          type: string
          example: "Bearer"

    RefreshTokenRequest:
      type: object
      required:
        - refreshToken
      properties:
        refreshToken:
          type: string
          example: "def50200f8b75b3a85b78e2686e6df8..."

    UserListResponse:
      type: object
      required:
        - users
        - pagination
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/User'
        pagination:
          $ref: '#/components/schemas/Pagination'

    UserResponse:
      type: object
      required:
        - user
      properties:
        user:
          $ref: '#/components/schemas/User'

    UserRolesResponse:
      type: object
      required:
        - userId
        - roles
      properties:
        userId:
          type: integer
          format: int64
          example: 123
        roles:
          type: array
          items:
            $ref: '#/components/schemas/Role'

    Role:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
          example: 1
        name:
          type: string
          example: "user"
        description:
          type: string
          example: "Regular user role"
          nullable: true
        permissions:
          type: array
          items:
            type: string
          example: ["read:profile", "write:profile"]

    Pagination:
      type: object
      required:
        - page
        - limit
        - total
        - totalPages
      properties:
        page:
          type: integer
          example: 1
        limit:
          type: integer
          example: 20
        total:
          type: integer
          example: 125
        totalPages:
          type: integer
          example: 7

    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              example: "VALIDATION_ERROR"
            message:
              type: string
              example: "Validation failed"
            details:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                    example: "email"
                  message:
                    type: string
                    example: "Email is required"

  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    Conflict:
      description: Resource conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    ValidationError:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT access token

security:
  - bearerAuth: []
代码yaml复杂

高级电商 API

完整的电商 API,包含产品、订单、支付和库存管理

标签

openapi, ecommerce, products, orders, payments, inventory

yaml
openapi: 3.0.3
info:
  title: E-commerce Platform API
  description: Comprehensive e-commerce API with product catalog, shopping cart, orders, payments, and inventory management
  version: 3.2.0
  contact:
    name: API Team
    email: api@ecommerce.com
    url: https://ecommerce.com/api-docs
  termsOfService: https://ecommerce.com/terms
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.ecommerce.com/v3
    description: Production server
  - url: https://staging-api.ecommerce.com/v3
    description: Staging server
  - url: https://sandbox-api.ecommerce.com/v3
    description: Sandbox environment

tags:
  - name: products
    description: Product catalog operations
  - name: cart
    description: Shopping cart operations
  - name: orders
    description: Order management operations
  - name: payments
    description: Payment processing operations
  - name: inventory
    description: Inventory management operations

paths:
  /products:
    get:
      tags:
        - products
      summary: List products
      description: Returns a paginated list of products with filtering and sorting options
      security:
        - apiKeyAuth: []
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: category
          in: query
          schema:
            type: string
        - name: minPrice
          in: query
          schema:
            type: number
            format: float
            minimum: 0
        - name: maxPrice
          in: query
          schema:
            type: number
            format: float
            minimum: 0
        - name: search
          in: query
          schema:
            type: string
        - name: sortBy
          in: query
          schema:
            type: string
            enum: [price, name, created_at, rating]
            default: created_at
        - name: sortOrder
          in: query
          schema:
            type: string
            enum: [asc, desc]
            default: desc
        - name: inStock
          in: query
          schema:
            type: boolean
        - name: tags
          in: query
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: Products retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductListResponse'
              examples:
                electronics_filter:
                  summary: Products filtered by electronics category
                  value:
                    products:
                      - id: 1
                        name: "Smartphone X"
                        price: 699.99
                        category: "Electronics"
                        inStock: true
                        rating: 4.5
                        images:
                          - "https://example.com/products/1/image1.jpg"
                    pagination:
                      page: 1
                      limit: 20
                      total: 45
                      totalPages: 3

    post:
      tags:
        - products
      summary: Create product
      description: Creates a new product in the catalog
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProductRequest'
            multipart/form-data:
              schema:
                $ref: '#/components/schemas/CreateProductFormData'
      responses:
        '201':
          description: Product created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductResponse'

  /products/{productId}:
    get:
      tags:
        - products
      summary: Get product by ID
      description: Returns detailed information about a specific product
      security:
        - apiKeyAuth: []
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Product retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductDetailResponse'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - products
      summary: Update product
      description: Updates product information
      security:
        - bearerAuth: []
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProductRequest'
      responses:
        '200':
          description: Product updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductResponse'

    delete:
      tags:
        - products
      summary: Delete product
      description: Removes a product from the catalog
      security:
        - bearerAuth: []
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Product deleted successfully

  /cart:
    get:
      tags:
        - cart
      summary: Get shopping cart
      description: Returns the current user's shopping cart
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Shopping cart retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartResponse'

    post:
      tags:
        - cart
      summary: Add item to cart
      description: Adds a product to the shopping cart
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddToCartRequest'
      responses:
        '201':
          description: Item added to cart successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartItemResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - cart
      summary: Update cart item quantity
      description: Updates the quantity of an item in the cart
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCartItemRequest'
      responses:
        '200':
          description: Cart item updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartItemResponse'

    delete:
      tags:
        - cart
      summary: Remove item from cart
      description: Removes an item from the shopping cart
      security:
        - bearerAuth: []
      parameters:
        - name: itemId
          in: query
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Item removed from cart

  /orders:
    get:
      tags:
        - orders
      summary: List orders
      description: Returns a paginated list of user orders
      security:
        - bearerAuth: []
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
        - name: status
          in: query
          schema:
            type: string
            enum: [pending, processing, shipped, delivered, cancelled]
        - name: dateFrom
          in: query
          schema:
            type: string
            format: date
        - name: dateTo
          in: query
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Orders retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderListResponse'

    post:
      tags:
        - orders
      summary: Create order
      description: Creates a new order from the shopping cart
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '201':
          description: Order created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'

  /orders/{orderId}:
    get:
      tags:
        - orders
      summary: Get order by ID
      description: Returns detailed information about a specific order
      security:
        - bearerAuth: []
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Order retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderDetailResponse'

  /payments:
    post:
      tags:
        - payments
      summary: Process payment
      description: Processes payment for an order
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
      responses:
        '200':
          description: Payment processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
        '400':
          $ref: '#/components/responses/PaymentError'
        '402':
          $ref: '#/components/responses/PaymentFailed'

components:
  schemas:
    Product:
      type: object
      required:
        - id
        - name
        - price
        - category
        - inStock
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          example: "550e8400-e29b-41d4-a716-446655440000"
          readOnly: true
        name:
          type: string
          example: "Wireless Headphones"
          maxLength: 200
        description:
          type: string
          example: "Premium noise-cancelling wireless headphones"
          maxLength: 1000
        price:
          type: number
          format: float
          example: 199.99
          minimum: 0
        originalPrice:
          type: number
          format: float
          example: 299.99
          nullable: true
        currency:
          type: string
          example: "USD"
          default: "USD"
        category:
          type: string
          example: "Electronics"
        subcategory:
          type: string
          example: "Audio"
          nullable: true
        brand:
          type: string
          example: "TechBrand"
          maxLength: 100
        sku:
          type: string
          example: "WH-NC-001"
          maxLength: 50
        images:
          type: array
          items:
            type: string
            format: uri
          maxItems: 10
        tags:
          type: array
          items:
            type: string
          maxItems: 20
        inStock:
          type: boolean
          example: true
        inventory:
          type: integer
          example: 150
          minimum: 0
        weight:
          type: number
          format: float
          example: 0.5
          nullable: true
        dimensions:
          $ref: '#/components/schemas/Dimensions'
        rating:
          type: number
          format: float
          example: 4.5
          minimum: 0
          maximum: 5
        reviewCount:
          type: integer
          example: 328
          minimum: 0
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true

    Dimensions:
      type: object
      properties:
        length:
          type: number
          format: float
          example: 7.5
        width:
          type: number
          format: float
          example: 6.2
        height:
          type: number
          format: float
          example: 3.1
        unit:
          type: string
          example: "inches"
          default: "inches"

    CreateProductRequest:
      type: object
      required:
        - name
        - price
        - category
        - inventory
      properties:
        name:
          type: string
          example: "Wireless Headphones"
          maxLength: 200
        description:
          type: string
          example: "Premium noise-cancelling wireless headphones"
          maxLength: 1000
        price:
          type: number
          format: float
          example: 199.99
          minimum: 0
        originalPrice:
          type: number
          format: float
          example: 299.99
          nullable: true
        category:
          type: string
          example: "Electronics"
        subcategory:
          type: string
          example: "Audio"
          nullable: true
        brand:
          type: string
          example: "TechBrand"
          maxLength: 100
        sku:
          type: string
          example: "WH-NC-001"
          maxLength: 50
        tags:
          type: array
          items:
            type: string
          maxItems: 20
        inventory:
          type: integer
          example: 150
          minimum: 0
        weight:
          type: number
          format: float
          example: 0.5
          nullable: true
        dimensions:
          $ref: '#/components/schemas/Dimensions'

    CreateProductFormData:
      type: object
      required:
        - name
        - price
        - category
        - inventory
      properties:
        name:
          type: string
          maxLength: 200
        description:
          type: string
          maxLength: 1000
        price:
          type: number
          format: float
          minimum: 0
        category:
          type: string
        inventory:
          type: integer
          minimum: 0
        images:
          type: array
          items:
            type: string
            format: binary

    UpdateProductRequest:
      allOf:
        - $ref: '#/components/schemas/CreateProductRequest'

    ProductResponse:
      type: object
      required:
        - product
      properties:
        product:
          $ref: '#/components/schemas/Product'

    ProductListResponse:
      type: object
      required:
        - products
        - pagination
      properties:
        products:
          type: array
          items:
            $ref: '#/components/schemas/Product'
        pagination:
          $ref: '#/components/schemas/Pagination'
        filters:
          type: object
          properties:
            applied:
              type: array
              items:
                type: string
            available:
              type: array
              items:
                type: string

    ProductDetailResponse:
      type: object
      required:
        - product
      properties:
        product:
          $ref: '#/components/schemas/Product'
        relatedProducts:
          type: array
          items:
            $ref: '#/components/schemas/Product'
        reviews:
          type: array
          items:
            $ref: '#/components/schemas/Review'

    Cart:
      type: object
      required:
        - id
        - items
        - subtotal
        - tax
        - total
        - currency
      properties:
        id:
          type: string
          format: uuid
          example: "550e8400-e29b-41d4-a716-446655440000"
          readOnly: true
        items:
          type: array
          items:
            $ref: '#/components/schemas/CartItem'
        subtotal:
          type: number
          format: float
          example: 89.97
        tax:
          type: number
          format: float
          example: 7.20
        shipping:
          type: number
          format: float
          example: 5.99
        discount:
          type: number
          format: float
          example: 10.00
        total:
          type: number
          format: float
          example: 93.16
        currency:
          type: string
          example: "USD"
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true

    CartItem:
      type: object
      required:
        - id
        - product
        - quantity
        - unitPrice
        - totalPrice
      properties:
        id:
          type: string
          format: uuid
          example: "550e8400-e29b-41d4-a716-446655440000"
          readOnly: true
        product:
          $ref: '#/components/schemas/Product'
        quantity:
          type: integer
          example: 2
          minimum: 1
          maximum: 99
        unitPrice:
          type: number
          format: float
          example: 29.99
          readOnly: true
        totalPrice:
          type: number
          format: float
          example: 59.98
          readOnly: true
        addedAt:
          type: string
          format: date-time
          readOnly: true

    AddToCartRequest:
      type: object
      required:
        - productId
        - quantity
      properties:
        productId:
          type: string
          format: uuid
        quantity:
          type: integer
          minimum: 1
          maximum: 99

    UpdateCartItemRequest:
      type: object
      required:
        - itemId
        - quantity
      properties:
        itemId:
          type: string
          format: uuid
        quantity:
          type: integer
          minimum: 1
          maximum: 99

    CartItemResponse:
      type: object
      required:
        - item
      properties:
        item:
          $ref: '#/components/schemas/CartItem'

    CartResponse:
      type: object
      required:
        - cart
      properties:
        cart:
          $ref: '#/components/schemas/Cart'

    Order:
      type: object
      required:
        - id
        - items
        - status
        - total
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          example: "550e8400-e29b-41d4-a716-446655440000"
          readOnly: true
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        status:
          type: string
          enum: [pending, processing, shipped, delivered, cancelled]
          example: "processing"
        subtotal:
          type: number
          format: float
          example: 89.97
        tax:
          type: number
          format: float
          example: 7.20
        shipping:
          type: number
          format: float
          example: 5.99
        discount:
          type: number
          format: float
          example: 10.00
        total:
          type: number
          format: float
          example: 93.16
        currency:
          type: string
          example: "USD"
        shippingAddress:
          $ref: '#/components/schemas/Address'
        billingAddress:
          $ref: '#/components/schemas/Address'
        trackingNumber:
          type: string
          example: "1Z9999W99999999999"
          nullable: true
        estimatedDelivery:
          type: string
          format: date
          example: "2025-12-05"
          nullable: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true

    CreateOrderRequest:
      type: object
      required:
        - shippingAddress
        - billingAddress
        - paymentMethod
      properties:
        shippingAddress:
          $ref: '#/components/schemas/Address'
        billingAddress:
          $ref: '#/components/schemas/Address'
        paymentMethod:
          type: string
          enum: [credit_card, debit_card, paypal, bank_transfer]
        notes:
          type: string
          maxLength: 500

    OrderResponse:
      type: object
      required:
        - order
      properties:
        order:
          $ref: '#/components/schemas/Order'

    OrderDetailResponse:
      type: object
      required:
        - order
      properties:
        order:
          $ref: '#/components/schemas/Order'

    OrderListResponse:
      type: object
      required:
        - orders
        - pagination
      properties:
        orders:
          type: array
          items:
            $ref: '#/components/schemas/Order'
        pagination:
          $ref: '#/components/schemas/Pagination'

    OrderItem:
      type: object
      required:
        - product
        - quantity
        - unitPrice
        - totalPrice
      properties:
        product:
          $ref: '#/components/schemas/Product'
        quantity:
          type: integer
          example: 2
          minimum: 1
        unitPrice:
          type: number
          format: float
          example: 29.99
          readOnly: true
        totalPrice:
          type: number
          format: float
          example: 59.98
          readOnly: true

    Address:
      type: object
      required:
        - street
        - city
        - state
        - postalCode
        - country
      properties:
        street:
          type: string
          example: "123 Main St"
          maxLength: 200
        street2:
          type: string
          example: "Apt 4B"
          maxLength: 200
          nullable: true
        city:
          type: string
          example: "New York"
          maxLength: 100
        state:
          type: string
          example: "NY"
          maxLength: 50
        postalCode:
          type: string
          example: "10001"
          maxLength: 20
        country:
          type: string
          example: "USA"
          maxLength: 50

    PaymentRequest:
      type: object
      required:
        - orderId
        - paymentMethod
        - amount
      properties:
        orderId:
          type: string
          format: uuid
          example: "550e8400-e29b-41d4-a716-446655440000"
        paymentMethod:
          type: string
          enum: [credit_card, debit_card, paypal, bank_transfer]
          example: "credit_card"
        paymentDetails:
          oneOf:
            - $ref: '#/components/schemas/CreditCardPayment'
            - $ref: '#/components/schemas/PayPalPayment'
            - $ref: '#/components/schemas/BankTransferPayment'
        amount:
          type: number
          format: float
          example: 93.16
        currency:
          type: string
          example: "USD"
        savePaymentMethod:
          type: boolean
          example: false

    CreditCardPayment:
      type: object
      required:
        - cardNumber
        - expiryMonth
        - expiryYear
        - cvv
      properties:
        cardNumber:
          type: string
          example: "4111111111111111"
        expiryMonth:
          type: integer
          minimum: 1
          maximum: 12
          example: 12
        expiryYear:
          type: integer
          minimum: 2025
          example: 2030
        cvv:
          type: string
          minLength: 3
          maxLength: 4
          example: "123"
        cardholderName:
          type: string
          example: "John Doe"

    PayPalPayment:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
          example: "buyer@example.com"
        payerId:
          type: string
          example: "PAYER12345"

    BankTransferPayment:
      type: object
      required:
        - bankName
        - accountNumber
      properties:
        bankName:
          type: string
          example: "Example Bank"
        accountNumber:
          type: string
          example: "****1234"
        routingNumber:
          type: string
          example: "021000021"

    PaymentResponse:
      type: object
      required:
        - paymentId
        - status
        - amount
        - currency
      properties:
        paymentId:
          type: string
          format: uuid
          example: "550e8400-e29b-41d4-a716-446655440000"
        status:
          type: string
          enum: [pending, processing, completed, failed, cancelled]
          example: "completed"
        transactionId:
          type: string
          example: "txn_1234567890"
          nullable: true
        amount:
          type: number
          format: float
          example: 93.16
        currency:
          type: string
          example: "USD"
        processedAt:
          type: string
          format: date-time
          nullable: true
        receiptUrl:
          type: string
          format: uri
          example: "https://example.com/receipts/txn_1234567890"
          nullable: true

    Pagination:
      type: object
      required:
        - page
        - limit
        - total
        - totalPages
      properties:
        page:
          type: integer
          example: 1
        limit:
          type: integer
          example: 20
        total:
          type: integer
          example: 125
        totalPages:
          type: integer
          example: 7
        hasNext:
          type: boolean
          example: true
        hasPrev:
          type: boolean
          example: false

    Review:
      type: object
      required:
        - id
        - rating
        - comment
        - reviewer
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          example: "550e8400-e29b-41d4-a716-446655440000"
        rating:
          type: integer
          example: 4
          minimum: 1
          maximum: 5
        comment:
          type: string
          example: "Great product, works as expected!"
          maxLength: 1000
        reviewer:
          type: object
          properties:
            name:
              type: string
              example: "John D."
            avatar:
              type: string
              format: uri
              example: "https://example.com/avatars/john.jpg"
        verified:
          type: boolean
          example: true
        helpful:
          type: integer
          example: 12
        createdAt:
          type: string
          format: date-time
          readOnly: true

    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              example: "PAYMENT_DECLINED"
            message:
              type: string
              example: "Payment was declined by the processor"
            details:
              type: object
              additionalProperties: true

  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    PaymentFailed:
      description: Payment processing failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    PaymentError:
      description: Payment error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for public endpoints

    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT access token for authenticated endpoints

security:
  - apiKeyAuth: []
  - bearerAuth: []

工具

经常与该案例搭配使用的工具

相关内容

相关案例集合

相关内容

相关专题

专题

OpenAPI 实用工作流

从 OpenAPI 生成类型与文档,审查破坏性变更,校验响应,并用压力与变异测试加固契约。

专题

JSON Schema 与 API 契约校验工具

在一个专题中比较 JSON Schema 校验、OpenAPI 响应检查、变异测试、压力测试和破坏性变更检测工具,适合 API 契约审查流程。

专题

API 契约定义、Schema 校验与变更测试

定义 API 契约,校验 Schema 和已捕获载荷,识别兼容性风险,并记录测试验收结果。

专题

API 请求格式检查、重放准备与调试工具

检查请求结构,准备本地重放,对比响应并定位 API 调试线索。工具只做本地分析或生成,不能代替真实鉴权和服务端测试。

首页
工具3212
案例593
可视化471
文件查看器103
专题239
标签333
图像、音频与视频657

图像、音频、视频处理、转换与优化工具

数学、日期与金融647

计算器、数值计算、日期逻辑、统计与金融工具

设计与颜色298

颜色、版式、图形、视觉样式与设计辅助工具

文本与写作209

写作、清洗、格式化、提取与文本分析工具

开发与 Web193

开发者工具、网络处理、Web 调试与自动化辅助工具

转换与编码175

格式、文件、压缩包、单位与编码转换工具

潜客测验发布与联系人交接
讣告、悼词与纪念卡的家属复核及交付
本地习惯记录的备份、恢复演练与分享前检查
长文改编 X 串文与 LinkedIn 帖子的事实复核与交付
Markdown 互动课件审校、离线演示与交付

© 2026 Elysia Tools. 保留所有权利。

文档价格关于我们服务条款隐私政策Cookie 政策联系我们

Development

OpenAPI 转 Postman Collection

把 OpenAPI 3.x 或 Swagger 2.0 规范(JSON/YAML)转成可直接导入的 Postman Collection v2.1.0,含文件夹、变量、认证与示例响应。

Validation

OpenAPI / Swagger 校验器

对 OpenAPI 3.0/3.1 与 Swagger 2.0 文档进行结构校验:必填字段、路径/操作完整性、响应码、$ref 引用解析、operationId 唯一性与组件完整性

Format Conversion

TOML / INI / HCL / .env / Nix / dotenv / Kubernetes ConfigMap / Secret 配置格式桥

在 dotenv .env、TOML、INI、Java .properties、YAML、JSON、HCL(Terraform/Vagrant 原生语法)与 Nix 属性集之间转换配置,并可输出 Kubernetes ConfigMap / Secret 清单;保留 ${VAR} / {{var}} 模板占位符与 envsubst 风格插值、记录类型推断来源(string/int/float/bool/list)、HCL 块标签自动折叠为嵌套键,往返 diff 突出非等价设置(丢失键、类型变化、值改写),输出对 Kustomize 补丁友好的 YAML。

Development

配置文件语义 Diff

比较 JSON、YAML、TOML 和 dotenv 配置,按键路径显示变化并忽略排序与格式噪声。

Development

环境配置差异可视化器

对 JSON、YAML、TOML 与 ENV 配置进行跨环境对比,高亮漂移项、缺失项,并给出清洗建议。

Format Conversion

HCL-YAML转换器

在HashiCorp配置语言(HCL)和YAML格式之间转换,用于Terraform配置

Data Processing

JSONata 查询转换工作室

预览 JSONata 风格查询与转换,支持多数据对比,并导出 JSON、CSV、YAML 或 Markdown。

Development

OpenAPI 转 TypeScript 类型生成器

将 OpenAPI 或 Swagger 的 JSON/YAML 规范转换为 TypeScript 接口类型、请求参数类型和响应类型,并支持输出格式与命名风格配置

API 文档

OpenAPI/Swagger 示例

使用 OpenAPI 3.0 和 Swagger 规范的 RESTful 服务综合 API 文档示例

可观测性

分布式追踪示例

使用 Jaeger、OpenTelemetry 和其他现代可观测性工具的综合分布式追踪示例,适用于微服务架构

监控

Grafana 高级应用示例

全面的 Grafana 示例,涵盖高级仪表板设计、告警配置、数据源集成和插件开发

可观测性与监控

Prometheus 监控

全面的 Prometheus 监控和告警系统示例,包括自定义指标导出器、告警规则配置、PromQL 查询和 Grafana 仪表板集成

CI/CD

CircleCI 配置示例

CircleCI配置示例,包括workflows、orbs、缓存和高级部署策略

服务网格

Consul 服务网格示例

HashiCorp Consul 服务网格示例,包含服务发现、配置和安全性