YAML OpenAPI Specification Related Articles API

related-articles

openapi: 3.0.0
info:
  version: 1.0.0
  title: Related Articles
  description: Manage related articles for blog post
  contact:
    name: Support
    email: jretz@jrts.info
paths: 
  /article/related/{id}:
    get:
      parameters:
      - name: id
        in: path
        description: ID of article
        required: true
        schema:
          type: string
        example: 20
      description: Returns the article ID and the IDs of related articles.
      responses:
        '200':
          description: List of related articles.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/relatedArticles'
              examples:
                success:
                  $ref: '#/components/examples/successWithIds'
                successNoIds:
                  $ref: '#/components/examples/successWithoutIds'
        '404':
          description: Article ID could not be found
          content:
            'applications/json':
              schema:
                $ref: '#/components/schemas/error'
              examples:
                success:
                  $ref: '#/components/examples/error'
    patch:
      summary: Updates an article with related article IDs
      operationId: updateRelatedIds
      parameters:
      - name: id
        in: path
        description: ID of article that needs to be updated
        required: true
        schema:
          type: string
        example: 10
      requestBody:
        content:
          'application/json':
            schema:
             type: object
             properties:
                ids: 
                  description: IDs to add to the list
                  type: array
                  items:
                    type: string
                  example: ['4', '5', '6']
             required:
               - ids
            examples:
              patchBody:
                $ref: '#/components/examples/patchBody'
              
      responses:
        '200':
          description: Article updated.
          content: 
            'application/json':
              schema:
                type: object
                items:
                  $ref: '#/components/schemas/relatedArticles'
              examples:
                success:
                  $ref: '#/components/examples/patchSuccess'

        '404':
          description: Article not found
          content: 
            'application/json':
              schema:
                type: object
                items:
                  $ref: '#/components/schemas/error'
              examples:
                notFound:
                  $ref: '#/components/examples/error'
  /article/generate:
    post:
      summary: Finds related articles and returns the IDs
      operationId: generateRelatedIds
      requestBody:
        content:
          'application/json':
            schema:
             type: object
             properties:
                id: 
                  description: ID of article
                  type: string
                  example: 20
                title:
                  description: Title of article
                  type: string
                  example: Inheritance with Python
                category:
                  description: Parent category
                  type: string
                  example: tech
                subCategories:
                  description: Any subcategories of parent
                  type: array
                  items:
                    type: string
                  example: ['Python', 'Building a Python Package']
                tags:
                  description: Tags for article
                  type: array
                  items:
                    type: string
                  example: ['api', 'python', 'fastapi']
             required:
               - id
               - title
            examples:
              generateBody:
                $ref: '#/components/examples/generateBody'
              
      responses:
        '200':
          description: Found related articles
          content: 
            'application/json':
              schema:
                type: object
                properties:
                  ids:
                    items:
                      type: string
                    example: ['7', '8', '9']
              examples:
                success:
                  $ref: '#/components/examples/generateSuccess'

        '404':
          description: Article not found
          content: 
            'application/json':
              schema:
                type: object
                items:
                  $ref: '#/components/schemas/error'
              examples:
                notFound:
                  $ref: '#/components/examples/error'
      
      
          
servers:
  # Added by API Auto Mocking Plugin
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/jdretz/related-articles/1.0.0
components:
  schemas:
    relatedArticles:
      type: object
      properties:
        articleId:
          type: string
        related:
          type: array
          items:
            type: string
    error:
      type: object
      properties:
        detail:
          type: string
      description: Error object
  examples:
      successWithoutIds:
        value:
          articleId: 20
          related: []
      successWithIds:
        value:
          articleId: 10
          related: ['1', '2', '3']
      error:
        value:
          detail: 'Not found.'
      patchBody:
        value:
          ids: ['4', '5', '6']
      patchSuccess:
        value:
          articleId: 10
          related: ['4', '5', '6']
      generateSuccess:
        value:
          articleId: 20
          ids: ['7', '8', '9']
      generateBody:
        value:
          id: 20
          title: Inheritance With Python
          category: tech
          subCategories: ['Python', 'Building a Python Package']
          tags: [api, python ,fastapi]