Swagger Demo


原文链接: Swagger Demo
# swagger,指定swagger spec版本,2.0
swagger: '2.0'
# info,提供API的元数据
info:
  title: Chirp API
  description: Chirp API
  version: "1.0.0"

# the domain of the service
host: demo.linyibr.com


# schemes,API的传输协议,http,https,ws,wss
schemes:
  - http
  - https

# basePath,相对于host的路径
# will be prefixed to all paths
# basePath: /v1

# Consumes 消费者  客户端请求 `Request` 的内容类型  
consumes:
  - application/json
  - application/x-www-form-urlencoded 
  - multipart/form-data
# Produces 生产者  服务端响应 `response` 的内容类型  
# produces:
#   - application/json

# paths ,API的路径,以及每个路径的HTTP方法,一个路径加上一个HTTP方法构成了一个操作。每个操作都有以下内容:
#       method HTTP方法 [get post put delete options head patch ]
#       tags,操作的标签
#       summary,短摘要
#       description,描述
#       externalDocs,外部文档
#       operationId,标识操作的唯一字符串
#       consumes,MIME类型列表
#       produces,MIME类型列表
#       parameters,参数列表
#         name 	        string 	  必填。参数名,大小写敏感。
#         in 	          string 	  必填。参数的位置,可能的值有:query、header、path、formData和body。
          # 有五种可能的参数类型:
          #     Path - 和路径模板一起使用,也就是说参数本身是路径的一部分。相对路径。例如:/items/{itemId}中,itemId为参数。
          #     Query - 添加在URL上的查询参数。例如:/items?id=###中,查询参数为id。
          #     Header - 自定义的请求头参数。
          #     Body - 附加到HTTP请求的payload。因为一个请求只能有一个payload,所以也只能有一个Body参数。body参数的名称本身并没有什么影响。考虑到Form本身也是一种Body,所以对于同一个操作,Form和Body不能共存。
          #     FormData - 当请求的 "content-type: application/x-www-form-urlencoded"
                # <form>属性enctype="multipart/form-data"共有二个值可选,这个属性管理的是表单的MIME编码:
                #  ① application/x-www-form-urlencoded(默认值) # 主要用来处理表单填写
                #  ② multipart/form-data                      # 主要用来做文件上传使用 
 #         description: 	string 	  参数的简述。支持GFM
#         required: 	    boolean 	参数是否必填。如果说in的值为path,那么required值必须为true。
#         schema:
#       responses,应答状态码和对于的消息的Schema
#       schemes,传输协议
#       deprecated,不推荐使用
#       security,安全

securityDefinitions:
  api_key:
    description: Authorization token using Bearer schema.
    type: "apiKey"
    name: "Authorization"
    in: "header"  
#全局增加安全认证 
# security:
#   - api_key: []

responses:
  401:
      description: Bad request.
      schema:
        properties:
          errors:
            type: array
            items:
              type: string            
            description: Error message.
paths:
  # curl 192.168.1.217/signup -H  "content-type: application/json" -d '{  "username": "string",  "password": "string",  "name": "string",  "email": "string@163.com"}'
  /signup:
      post:        
        tags: [AuthUsers]
        summary: Creates a new user.
        parameters:
          - name: user_data
            in: body
            description: New user data.
            required: true
            schema:
              $ref: '#/definitions/AuthUser'

        responses:
          201:
            description: New user.
            headers:
              Location:
                description: Path to the newly created user.
                type: string
            schema:
              $ref: '#/definitions/User'
          400:
            description: Bad request.
            schema:
              properties:
                error:
                  type: string
                  description: Error message.
          500:
            description: Unexpected error happened.
            schema:
              properties:
                error:
                  type: string
                  description: Error message.

  /login:
    post:
      tags: [AuthUsers, Users]
      summary: Logs in a user.
      parameters:
        # - name: email
        #   in: formData
        #   type: string
        #   description: Email of a user that attempts a login.
        #   # required: true
        # - name: password
        #   in: formData
        #   type: string
        #   description: Password of a user that attempts a login.

        - name: user_login
          in: body
          schema:
            type: object
            properties:
              email:
                type: string
              password:
                type: string


      responses:
        200:
          description: Users authentication token.
          schema:
            $ref: '#/definitions/LoginResponse'
        400:
          description: Bad request.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        401:
          description: Invalid email or password.
          schema:
            properties:
              errors:
                type: array
                items:
                  type: string
                description: Error message.
        500:
          description: Unexpected error happened.
          schema:
            properties:
              error:
                type: string
                description: Error message.

  /token:
    post:
      tags: [AuthUsers]
      summary: Refreshes auth token using refresh token
      parameters:
        # - name: refresh_token
        #   in: query
        #   type: string
        #   description: Refresh token obtained when logging in
        #   required: true
        - name: refresh_token
          in: body
          schema:
            type: object
            properties:
              refresh_token:
                type: string

      responses:
        200:
          description: New authentication token
          schema:
            $ref: '#/definitions/RefreshAuthTokenResponse'
        400:
          description: Bad request.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        500:
          description: Unexpected error happened.
          schema:
            properties:
              error:
                type: string
                description: Error message.

  /auth/{user_id}:
    patch:
      deprecated: true
      tags: [AuthUsers]
      summary: Updates authentication and account data of a user with given ID.
      parameters:
        - name: user_id
          in: path
          description: ID of the user.
          required: true
          type: integer
          format: int64
        - name: user_data
          in: body
          description: New user data.
          required: true
          schema:
            $ref: '#/definitions/AuthUser'
      responses:
        200:
          description: Updated user.
          schema:
            $ref: '#/definitions/User'
        400:
          description: Bad request.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        404:
          description: User with given ID does not exist.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        500:
          description: Unexpected error happened.
          schema:
            properties:
              error:
                type: string
                description: Error message.

  /users:
    get:
      deprecated: true
      tags: [Users]
      summary: Get list of users.
      description: |
        The users endpoint returns list of users that fulfill given
        search criteria.
      parameters:
        - name: Authorization
          in: header
          type: string
          required: true
          description: Authorization token using Bearer schema.
        - name: username
          in: query
          type: string
          description: Username of the user.
          required: false

      responses:
        200:
          description: An array of users.
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
        400:
          description: One of the query parameters is not supported.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        500:
          description: Unexpected error happened.
          schema:
            properties:
              error:
                type: string
                description: Error message.

  /users/{user_id}:
    get:
      tags: [Users]
      summary: Get data of a user with a given ID.
      security:
        - api_key: []
      parameters:    
        - name: user_id
          in: path
          description: ID of the user to follow.
          required: true
          type: integer
          format: int64

      responses:
        200:
          description: User with given ID.
          schema:
            $ref: '#/definitions/User'
        404:
          description: User with given ID does not exist.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        500:
          description: Unexpected error happened.
          schema:
            properties:
              error:
                type: string
                description: Error message.

  /users/{user_id}/follow:
    post:
      tags: [Users]
      summary: Authenticated user follows user with a given ID.
      security:
        - api_key: []
      parameters:
        - name: user_id
          in: path
          description: ID of the user to follow.
          required: true
          type: integer
          format: int64

      responses:
        200:
          description: User with given ID with updated follower count.
          schema:
            $ref: '#/definitions/User'
        400:
          description: User with given ID is already followed by the authenticating user.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        401:
          description: User authorization failed.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        404:
          description: User with given ID does not exist.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        500:
          description: Unexpected error happened.
          schema:
            properties:
              error:
                type: string
                description: Error message.

  /users/{user_id}/unfollow:
    post:
      summary: Authenticated user unfollows user with a given ID.
      security:
        - api_key: []
      parameters:
        - name: user_id
          in: path
          description: ID of the user to unfollow.
          required: true
          type: integer
          format: int64
      tags:
        - Users
      responses:
        200:
          description: User with given ID with updated follower count.
          schema:
            $ref: '#/definitions/User'
        400:
          description: User with given ID is not followed by the authenticating user.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        401:
          description: User authorization failed.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        404:
          description: User with given ID does not exist.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        500:
          description: Unexpected error happened.
          schema:
            properties:
              error:
                type: string
                description: Error message.

  /users/{user_id}/followers:
    get:
      summary: Get list of followers of user with a given ID.
      security:
        - api_key: []
      parameters:
        - name: user_id
          in: path
          description: ID of the user.
          required: true
          type: integer
          format: int64
      tags:
        - Users
      responses:
        200:
          description: An array of users that follow given user.
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
        404:
          description: User with given ID does not exist.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        500:
          description: Unexpected error happened.
          schema:
            properties:
              error:
                type: string
                description: Error message.

  /users/{user_id}/followees:
    get:
      summary: Get list of users followed by a user with a given ID.
      security:
        - api_key: []
      parameters:
        - name: user_id
          in: path
          description: ID of the user.
          required: true
          type: integer
          format: int64
      tags:
        - Users
      responses:
        200:
          description: An array of users that given user follows.
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
        404:
          description: User with given ID does not exist.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        500:
          description: Unexpected error happened.
          schema:
            properties:
              error:
                type: string
                description: Error message.

  /users/{user_id}/tweets:
    get:
      summary: Get list of tweets posted by user with a given ID.
      security:
        - api_key: []
      parameters:
        - name: user_id
          in: path
          description: ID of the user.
          required: true
          type: integer
          format: int64
      tags:
        - Tweets
      responses:
        200:
          description: An array of users tweets.
          schema:
            type: array
            items:
              $ref: '#/definitions/Tweet'
        400:
          description: Returned when user_id in path was not an integer.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        500:
          description: Unexpected error happened.
          schema:
            properties:
              error:
                type: string
                description: Error message.

  /feed:
    get:
      summary: Get authenticating users feed which is a combination of tweets of people he/she follows.
      parameters:
        - name: Authorization
          in: header
          type: string
          required: true
          description: Authorization token using Bearer schema.
      tags:
        - Home Timeline
      responses:
        200:
          description: An array of tweets that represents users feed.
          schema:
            type: array
            items:
              $ref: '#/definitions/Tweet'
        401:
          description: User authorization failed.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        500:
          description: Unexpected error happened.
          schema:
            properties:
              error:
                type: string
                description: Error message.

  /tweets:
    post:
      summary: Authenticating user adds a new tweet.
      security:
        - api_key: []
      parameters:
        - name: content
          in: body
          description: content of the tweet
          required: true
          schema:
            $ref: '#/definitions/NewTweet'
      tags:
        - Tweets
      responses:
        201:
          description: New tweet.
          headers:
            Location:
              description: Path to the newly created tweet.
              type: string
          schema:
            $ref: '#/definitions/Tweet'
        400:
          description: Invalid content.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        401:
          description: User authorization failed.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        500:
          description: Unexpected error happened.
          schema:
            properties:
              error:
                type: string
                description: Error message.

  /tweets/{tweet_id}:
    get:
      summary: Get a tweet with a given ID.
      security:
        - api_key: []
      parameters:
        - name: tweet_id
          in: path
          description: ID of the tweet.
          required: true
          type: integer
          format: int64
      tags:
        - Tweets
      responses:
        200:
          description: A single tweet.
          schema:
            $ref: '#/definitions/Tweet'
        404:
          description: Tweet with given ID does not exist.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        500:
          description: Unexpected error happened.
          schema:
            properties:
              error:
                type: string
                description: Error message.
    delete:
      summary: Authentication user deletes a tweet with a given ID.
      parameters:
        - name: Authorization
          in: header
          type: string
          required: true
          description: Authorization token using Bearer schema.
        - name: tweet_id
          in: path
          description: ID of the tweet.
          required: true
          type: integer
          format: int64
      tags:
        - Tweets
      responses:
        204:
          description: The tweet was sucesfully deleted.
        401:
          description: User authorization failed.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        403:
          description: User is not authorized to delete the tweet.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        404:
          description: Tweet with given ID does not exist.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        500:
          description: Unexpected error happened.
          schema:
            properties:
              error:
                type: string
                description: Error message.
    put:
      summary: Authenticating user updates a tweet with a given ID.
      parameters:
        - name: Authorization
          in: header
          type: string
          required: true
          description: Authorization token using Bearer schema.
        - name: tweet_id
          in: path
          description: ID of the tweet.
          required: true
          type: integer
          format: int64
        - name: content
          in: body
          description: Content of the tweet.
          required: true
          schema:
            $ref: '#/definitions/NewTweet'
      tags:
        - Tweets
      responses:
        200:
          description: Updated tweet.
          schema:
            $ref: '#/definitions/Tweet'
        400:
          description: Invalid request.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        401:
          description: User authorization failed.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        403:
          description: User is not authorized to edit the tweet.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        404:
          description: Tweet with given ID does not exist.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        500:
          description: Unexpected error happened.
          schema:
            properties:
              error:
                type: string
                description: Error message.

  /tweets/{tweet_id}/like:
    post:
      summary: Authenticating user likes a tweet with given ID.
      security:
        - api_key: []
      parameters:
        - name: tweet_id
          in: path
          description: ID of the tweet.
          required: true
          type: integer
          format: int64
      tags:
        - Tweets
      responses:
        200:
          description: Liked tweet with updated state.
          schema:
            $ref: '#/definitions/Tweet'
        404:
          description: Tweet with given ID does not exist.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        401:
          description: User authorization failed.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        500:
          description: Unexpected error happened.
          schema:
            properties:
              error:
                type: string
                description: Error message.

  /tweets/{tweet_id}/unlike:
    post:
      summary: Authenticating user unlikes a tweet with given ID.
      security:
        - api_key: []
      parameters:
        - name: tweet_id
          in: path
          description: ID of the tweet.
          required: true
          type: integer
          format: int64
      tags:
        - Tweets
      responses:
        200:
          description: Liked tweet with updated state.
          schema:
            $ref: '#/definitions/Tweet'
        404:
          description: Tweet with given ID does not exist.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        401:
          description: User authorization failed.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        500:
          description: Unexpected error happened.
          schema:
            properties:
              error:
                type: string
                description: Error message.

  /tweets/{tweet_id}/retweet:
    post:
      summary: Authenticating user retweets a tweet with given ID.
      security:
        - api_key: []
      parameters:
        - name: tweet_id
          in: path
          description: ID of the tweet.
          required: true
          type: integer
          format: int64
      tags:
        - Tweets
      responses:
        200:
          description: Retweeted tweet with updated state.
          schema:
            $ref: '#/definitions/Tweet'
        401:
          description: User authorization failed.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        404:
          description: Tweet with given ID does not exist.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        500:
          description: Unexpected error happened.
          schema:
            properties:
              error:
                type: string
                description: Error message.

  /tweets/{tweet_id}/unretweet:
    post:
      summary: Authenticating user unretweets a tweet with given ID.
      security:
        - api_key: []
      parameters:
        - name: tweet_id
          in: path
          description: ID of the tweet.
          required: true
          type: integer
          format: int64
      tags:
        - Tweets
      responses:
        200:
          description: Retweeted tweet with updated state.
          schema:
            $ref: '#/definitions/Tweet'
        401:
          description: User authorization failed.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        404:
          description: Tweet with given ID does not exist.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        500:
          description: Unexpected error happened.
          schema:
            properties:
              error:
                type: string
                description: Error message.

  /tweets/{tweet_id}/likers:
    get:
      summary: Returns likers of a given tweet.
      security:
        - api_key: []
      parameters:
        - name: tweet_id
          in: path
          description: ID of the tweet.
          required: true
          type: integer
          format: int64
      tags:
        - Tweets
      responses:
        200:
          description: An array of Users that liked given tweet.
          schema:
            type: array
            items:
              $ref: '#/definitions/User'

  /tweets/{tweet_id}/retweeters:
    get:
      summary: Returns retweeters of a given tweet.
      security:
        - api_key: []
      parameters:
        - name: tweet_id
          in: path
          description: ID of the tweet.
          required: true
          type: integer
          format: int64
      tags:
        - Tweets
      responses:
        200:
          description: An array of Users that retweeted given tweet.
          schema:
            type: array
            items:
              $ref: '#/definitions/User'

  
  /search:
    get:
      summary: Perform a full text search with a provided querystring on tweets
        content and users name and username.
      security:
        - api_key: []
      parameters:
        - name: QueryString
          in: query
          type: string
          required: true
          description: String on which the search will be performed.
      tags:
        - Search
      responses:
        200:
          description: Object containing array of users and tweets that match
            provided QueryString.
          schema:
            $ref: '#/definitions/SearchResponse'
        401:
          description: User authorization failed.
          schema:
            properties:
              error:
                type: string
                description: Error message.
        500:
          description: Unexpected error happened.
          schema:
            properties:
              error:
                type: string
                description: Error message.

definitions:
  User:
    type: object
    properties:
      id:
        type: integer
        format: int64
        description: ID of the user.
      username:
        type: string
        description: Username of the user.
      name:
        type: string
        description: Nick name of the user.
      avatar_url:
        type: string
        format: url
        description: An URL to users avatar.
      following:
        type: boolean
        description: Informs if authenticating user follows this user.

  AuthUser:
    type: object
    properties:
      username:
        type: string
      password:
        type: string
      name:
        type: string
      email:
        type: string

  LoginResponse:
    type: object
    properties:
      user:
        $ref: '#/definitions/User'
      auth_token:
        type: string
      refresh_token:
        type: string

  RefreshAuthTokenResponse:
    type: object
    properties:
      auth_token:
        type: string

  Tweet:
    type: object
    properties:
      id:
        type: integer
        format: int64
        description: ID of the tweet.
      author:
        $ref: '#/definitions/User'
      likes:
        type: integer
        format: int64
        description: Number of likes of the tweet.
      retweets:
        type: integer
        format: int64
        description: Number of retweets of the tweet.
      created_at:
        type: string
        format: date-time
        description: Creation time of the tweet.
      content:
        type: string
        description: Content of the tweet.
      liked:
        type: boolean
        description: Informs if authenticating user liked this tweet.
      retweeted:
        type: boolean
        description: Informs if authenticating user retweeted this tweet.


  NewTweet:
    type: object
    properties:
      content:
        type: string

  SearchResponse:
    type: object
    properties:
      users:
        type: array
        items:
          $ref: "#/definitions/User"
      tweets:
        type: array
        items:
          $ref: "#/definitions/Tweet"

`