swagger.yml

swagger.yml

openapi: 3.0.0
info:
  description:  Test API for retrieving information
  version: "1.0.0"
  title: Test API
paths:
  /articles:
    get:
      tags:
        - Articles
      summary: Retrieve a list of articles
      operationId: listArticles
      parameters: 
        - in: query
          name: limit
          description: specify the maximum number of articles to return
          required: true
          schema:
            type: integer
            format: int32
            minimum: 0
            maximum: 50
      responses:
        '200':
          description: List of articles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BasicArticle'
                  
  /articles/{uuid}:
    get:
      tags:
        - Articles
      parameters:
        - name: uuid
          in: path
          description: Article UUID
          required: true
          schema:
            type: string
            format: uuid
      summary: Retrieve a specific article
      operationId: getArticle
      responses:
        '200':
          description: Details of article
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Article'
              example:
                $ref: '#/components/examples/Article'
        
        '404':
          $ref: '#/components/responses/NotFound'
                
components:
  responses:
    NotFound:
      description: "The specified resource was not found"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
            
  schemas:
    Error:
      type: object
      properties:
        code:
          type: integer
        error:
          type: string
          
    Content:
      allOf:
        - type: object
          properties:
            id:
              type: integer
            title:
              type: string
            url:
              type: string
              format: uri
              description: "Link to the content on the website"
            thumbnail:
              type: string
              format: uri
              description: "Link to the thumbnail image for the content"
            author:
              $ref: '#/components/schemas/User'
            datetime:
              type: string
              format: date-time
              description: "Date/time of content publication"
            content_type:
              type: string
              description: "Content type for use in e.g. content reporting"
            vote_points:
              type: integer
              description: "Number of points the content has earned through user votes"
              
    BasicArticle:
      example:
        id: 42
        title: "Best Article Ever"
        url: "https://www.example.com/article/42"
        author: 
          id: 42
          uuid: "88b6a469-d0dc-448f-8aec-28621e5f205d"
          username: "user_1"
          avatar: "http://www.fillmurray.com/100/100"
        datetime: "2018-04-01 18:42:01Z"
        content_type: "Article"
        vote_points: 42
        summary: 'This is the article summary'
      allOf:
        - $ref: '#/components/schemas/Content'
        - type: object
          properties:
            summary:
              type: string
              format: html
              description: "Article summary"
              
    Article:
      allOf:
        - $ref: '#/components/schemas/Content'
        - $ref: '#/components/schemas/BasicArticle'
        - type: object
          properties:
            content:
              type: string
              format: html
              description: "Article content (HTML)"
              
    User:
      example:
        id: 42
        uuid: "88b6a469-d0dc-448f-8aec-28621e5f205d"
        username: "user_1"
        avatar: "http://www.fillmurray.com/100/100"
      properties:
        id:
          type: integer
        uuid:
          type: string
          format: uuid
        username:
          type: string
        avatar:
          type: string
          format: uri
      type: object
      
  examples:
    Article:
      id: 42
      title: "Best Article Ever"
      url: "https://www.example.com/article/42"
      author: 
        id: 42
        uuid: "88b6a469-d0dc-448f-8aec-28621e5f205d"
        username: "user_1"
        avatar: "http://www.fillmurray.com/100/100"
      datetime: "2018-04-01 18:42:01Z"
      content_type: "Article"
      vote_points: 42
      content: '<p>This is the article content</p>'