swagger_blog.yaml

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