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。
# 有五种可能的参数类型：
# 1. Path - 和路径模板一起使用，也就是说参数本身是路径的一部分。相对路径。例如：/items/{itemId}中，itemId为参数。
# 2. Query - 添加在URL上的查询参数。例如：/items?id=###中，查询参数为id。
# 3. Header - 自定义的请求头参数。
# 4. Body - 附加到HTTP请求的payload。因为一个请求只能有一个payload，所以也只能有一个Body参数。body参数的名称本身并没有什么影响。考虑到Form本身也是一种Body，所以对于同一个操作，Form和Body不能共存。
# 5. 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"