swagger -- ref 自定义的使用

最新推荐文章于 2025-04-24 10:26:30 发布

dongmelon

最新推荐文章于 2025-04-24 10:26:30 发布

阅读量6.1k

点赞数

CC 4.0 BY-SA版权

文章标签： swagger

本文链接：https://blog.youkuaiyun.com/dongmelon/article/details/78843090

Swagger 专栏收录该内容

1 篇文章

订阅专栏

本文介绍了一个简单的艺术家API设计案例，详细解析了如何使用Swagger规范来定义API接口，包括路径参数、请求体、响应状态等，并特别强调了400错误响应的标准化处理。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

400err定义了一个可重用的响应，它指定了我们在所有端点下使用的400响应，然后进行适当的引用。

swagger: '2.0'
info:
  version: 1.0.0
  title: Simple Artist API
  description: A simple API to understand the Swagger specification in greater detail
schemes: 
- https
host: example.io
basePath: /v1
securityDefinitions:
  UserSecurity:
    type: basic
security:
  - UserSecurity: [] 
paths:
  /artists:
    get:
      description: Returns a list of artists 
      parameters:
        - $ref: '#/parameters/PageLimit'
        - $ref: '#/parameters/PageNumber'
        
      responses:
        200:
          description: Successfully returned a list of artists 
          schema:
            type: array
            items:
              $ref: '#/definitions/Artist'
                  
        400:
          #  ----- Added line  ----------------------------------------
          $ref: '#/responses/400Error'
          #  ---- /Added line  ----------------------------------------
            
    post:
      description: Lets a user post a new artist
      parameters:
        - name: artist
          in: body
          description: creates a new artist in our database
          schema:
            $ref: '#/definitions/Artist'
                
      responses:
        200:
          description: Successfully created a new artist
          
        400:
          #  ----- Added line  ----------------------------------------
          $ref: '#/responses/400Error'
          #  ---- /Added line  ----------------------------------------
    
  /artists/{username}:
    get:
      description: Obtain information about an artist from his or her unique username
      parameters:
        - name: username
          in: path 
          type: string
          required: true 
          
      responses:
        200:
          description: Successfully returned an artist
          schema:
            type: object
            properties:
              artist_name:
                type: string
              artist_genre:
                type: string
              albums_recorded:
                type: integer
                
        400:
          #  ----- Added line  ----------------------------------------
          $ref: '#/responses/400Error'
          #  ---- /Added line  ----------------------------------------                
                
definitions:
  Artist:
    type: object
    required:
      - username
    properties:
      artist_name:
        type: string
      artist_genre:
          type: string
      albums_recorded:
          type: integer
      username:
          type: string
#  ----- Added lines  ----------------------------------------
parameters:
  PageLimit:
    name: limit
    in: query
    type: integer
    description: Limits the number of items on a page
    
  PageNumber:
    name: offset
    in: query
    type: integer
    description: Specifies the page number of the artists to be displayed
responses:
  400Error:
    description: Invalid request
    schema:
      type: object 
      properties:
        message:
          type: string
#  ---- /Added lines  ----------------------------------------