Example Blog API (includes problems to cause linting errors)

blog-api.yaml

openapi: 3.1.1
info:
  title: Blog Backend API
  version: 1.0.0
  description: API for managing blog posts, categories, and featured images. This API allows clients to create, retrieve, and manage blog content and organizational categories.

tags:
  - name: post
    description: Endpoints related to creating, retrieving, and managing blog posts and their associated resources, such as featured images.
  - name: category
    description: Endpoints for managing post categories, which are used to organize blog content.

paths:
  /posts:
    get:
      tags: [post]
      summary: Get all posts
      responses:
        '200':
          description: A list of all existing blog posts.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Post'
              examples:
                example:
                  value:
                    - id: 1
                      title: "Welcome to My Blog"
                      body: "First post content."
                      category:
                        id: 1
                        name: "General"
                      featuredImageUrl: "https://example.com/images/1.jpg"

    post:
      tags: [post]
      summary: Create a new post
      description: Create a new blog post and associate it with an existing category.
      operationId: createPost
      requestBody:
        description: Data for the new blog post, including title, body content, and category ID.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewPost'
            examples:
              example:
                value:
                  title: "New Blog Post"
                  body: "This is the post content."
                  categoryId: 2
      responses:
        '201':
          description: Successfully created blog post with its associated category.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
              examples:
                example:
                  value:
                    id: 2
                    title: "New Blog Post"
                    body: "This is the post content."
                    category:
                      id: 2
                      name: "Technology"
                    featuredImageUrl: null

  /posts/{postId}:
    get:
      tags: [post]
      summary: Get a single post
      description: Retrieve a specific blog post by its unique ID.
      operationId: getPost
      parameters:
        - name: postId
          in: path
          required: true
          description: Unique identifier of the blog post to retrieve.
          schema:
            type: integer
      responses:
        '200':
          description: The requested blog post.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
              examples:
                example:
                  value:
                    id: 1
                    title: "Welcome to My Blog"
                    body: "First post content."
                    category:
                      id: 1
                      name: "General"
                    featuredImageUrl: "https://example.com/images/1.jpg"
        '404':
          description: Post not found.

  /posts/{postId}/featured-image:
    post:
      tags: [post]
      summary: Upload a featured image for a post
      description: Upload or replace the featured image associated with a blog post.
      operationId: uploadFeaturedImage
      parameters:
        - name: postId
          in: path
          required: true
          description: Unique identifier of the post to associate the image with.
          schema:
            type: integer
      requestBody:
        description: Image file to be uploaded as the featured image.
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: Binary image file to upload.
      responses:
        '200':
          description: Featured image uploaded successfully.
        '404':
          description: Post not found.

  /categories:
    get:
      tags: [category]
      summary: Get all categories
      description: Retrieve a list of all available categories that can be used to organize blog posts.
      operationId: getCategories
      responses:
        '200':
          description: A list of all categories.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Category'
              examples:
                example:
                  value:
                    - id: 1
                      name: "General"
                    - id: 2
                      name: "Technology"

    post:
      tags: [category]
      summary: Create a new category
      description: Create a new category to organize blog posts.
      operationId: createCategory
      requestBody:
        description: Category data to create.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewCategory'
            examples:
              example:
                value:
                  name: "Health"
      responses:
        '201':
          description: Successfully created category.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
              examples:
                example:
                  value:
                    id: 3
                    name: "Health"

  /categories/{categoryId}:
    get:
      tags: [category]
      summary: Get a single category
      description: Retrieve a specific category by its unique ID.
      operationId: getCategory
      parameters:
        - name: categoryId
          in: path
          required: true
          description: Unique identifier of the category to retrieve.
          schema:
            type: integer
      responses:
        '200':
          description: The requested category.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
              examples:
                example:
                  value:
                    id: 1
                    name: "General"
        '404':
          description: Category not found.

components:
  schemas:
    Category:
      type: object
      description: Represents a category used to organize blog posts.
      properties:
        id:
          type: integer
          description: Unique identifier for the category.
          example: 1
        name:
          type: string
          description: The name of the category.
          example: Technology
      required:
        - id
        - name

    NewCategory:
      type: object
      description: Data required to create a new category.
      properties:
        name:
          type: string
          description: The name of the new category.
          example: Lifestyle
      required:
        - name

    Post:
      type: object
      description: Represents a blog post including its category and optional featured image.
      properties:
        id:
          type: integer
          description: Unique identifier for the post.
          example: 123
        title:
          type: string
          description: The title of the blog post.
          example: "My First Blog Post"
        body:
          type: string
          description: The main content body of the blog post.
          example: "This is the content of the blog post."
        category:
          $ref: '#/components/schemas/Category'
        featuredImageUrl:
          type: string
          format: uri
          nullable: true
          description: URL to the featured image if one is attached to the post.
          example: "https://example.com/images/123.jpg"
      required:
        - id
        - title
        - body
        - category

    NewPost:
      type: object
      description: Data required to create a new blog post.
      properties:
        title:
          type: string
          description: The title of the new blog post.
          example: "A Day in the Life"
        body:
          type: string
          description: The content body of the new blog post.
          example: "Here is what happened today..."
        categoryId:
          type: integer
          description: ID of the category to assign to the post.
          example: 1
      required:
        - title
        - body
        - categoryId

ruleset-spec-only.yaml

extends: [[spectral:oas, off]]
rules:
  oas3-schema: true

ruleset.yaml

extends: [[spectral:oas, off]]
rules:
  oas3-schema: true
  operation-operationId: true
  operation-operationId-unique: true

  operation-tag-defined: true
  tag-description: true

  operation-description: true
  schema-description: true
  component-description: true

  description-duplication: true