Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
swagger: "2.0"
info:
version: 1.0.0
title: blog
# description支持markdown
description: |
# blog API documentation
这篇文档描述了的blog(article)的api接口
# host: localhost:8000 #localhost blog
# basePath: /api
schemes:
- https
- http
consumes:
- application/json
produces:
- application/json
paths:
/:
get:
summary: Service root
description: 列出所有api的描述信息.
operationId: root
responses:
'200':
description: Success
security: []
/articles:
get:
summary: list all articles
operationId: list_all_articles #后端函数
responses:
'200':
#todo
description: Annotation successfully created
schema:
$ref: '#/definitions/ArticleList'
'400':
description: Could not create article from your request
schema:
$ref: '#/definitions/Error'
post:
summary: Create a new Article
operationId: createArticle
parameters:
- name: Article
in: body
description: article to be created
required: true
schema:
$ref: '#/definitions/NewArticle'
responses:
'200':
description: article successfully created
schema:
$ref: '#/definitions/Article'
'400':
description: Could not create article from your request
schema:
$ref: '#/definitions/Error'
/articles/{id}:
get:
summary: Fetch an Article
operationId: fetchArticle
parameters:
- name: id
in: path
description: ID of article to return
required: true
type: string
responses:
'200':
description: Success
schema:
$ref: '#/definitions/Article'
'404':
description: article not found or no permission to view
schema:
$ref: '#/definitions/Error'
patch:
summary: Update an Article
description: |
This endpoint is available under both the `PATCH` and `PUT`
request methods. Both endpoints have PATCH-characteristics
as defined in [RFC5789](https://tools.ietf.org/html/rfc5789#section-1),
meaning the request body does not have to include the whole Article
object.
New implementations should use the `PATCH` request method, and existing
implementations continue to work under `PUT` but should switch to `PATCH`.
operationId: updateArticle
parameters:
- name: id
in: path
description: ID of article to return
required: true
type: string
- name: Article
in: body
description: Updated article body
required: true
schema:
$ref: '#/definitions/NewArticle'
responses:
'200':
description: Success
schema:
$ref: '#/definitions/Article'
'400':
description: Could not create article from your request
schema:
$ref: '#/definitions/Error'
'404':
description: article not found or no permission to update
schema:
$ref: '#/definitions/Error'
delete:
summary: Delete an Article
operationId: deleteArticle
parameters:
- name: id
in: path
description: ID of article to return
required: true
type: string
responses:
'200':
description: Success
schema:
type: object
required:
- deleted
- id
properties:
deleted:
type: boolean
enum:
- true
id:
type: string
'404':
description: article not found or no permission to delete
schema:
$ref: '#/definitions/Error'
/search:
get:
summary: Search for annotations
operationId: search #后台对应的函数名
parameters:
- name: limit
in: query
description: The maximum number of annotations to return.
required: false
type: integer
minimum: 0
maximum: 200
default: 20
- name: offset
in: query
description: >
The minimum number of initial annotations to skip. This is
used for pagination.
required: false
type: integer
default: 0
minimum: 0
- name: sort
in: query
description: The field by which annotations should be sorted.
required: false
type: string
default: updated
responses:
'200':
description: Search results
schema:
$ref: '#/definitions/SearchResults'
definitions:
NewArticle:
# todo json 2 yaml: https://www.json2yaml.com/
# 也可以是在线的
#$ref: './schemas/annotation-schema.json' #https://h.readthedocs.io/en/latest/api/schemas/annotation-schema.json
type: object
properties:
userid:
type: string
#"pattern": "^acct:.+$"
title:
type: string
content:
type: string
tags:
type: array
items:
type: string
Article:
allOf:
- $ref: '#/definitions/NewArticle' # NewArticle属性展开在这里
- required:
- id
properties:
id:
type: string
Error:
type: object
required:
- status
properties:
status:
type: string
enum:
- failure
reason:
type: string
description: A human-readable description of the reason(s) for failure.
SearchResults:
#用作list
type: object
required:
- rows
- total
properties:
rows:
type: array
items:
$ref: '#/definitions/Article'
total:
description: Total number of results matching query.
type: integer
ArticleList:
#用作list
type: object
required:
- rows
- total
properties:
rows:
type: array
items:
$ref: '#/definitions/Article'
total:
description: Total number of results matching query.
type: integer
# Added by API Auto Mocking Plugin
host: virtserver.swaggerhub.com
basePath: /pwnote/blog/1.0.0
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.