{
  "openapi": "3.0.0",
  "info": {
    "title": "Changelog & Release Notes Generator API",
    "version": "1.0.0",
    "description": "Transform git commit messages into polished changelogs and release notes. Supports Markdown, GitHub Release, Slack, and JSON output. Auto-classifies commits using conventional commit prefixes and keyword detection. Calculates semver bump (major/minor/patch), extracts scopes, filters user-facing changes, and groups by section. Fully self-contained — no external API required."
  },
  "servers": [
    {
      "url": "https://changelog-generator.vercel.app"
    }
  ],
  "paths": {
    "/": {
      "get": {
        "summary": "List all endpoints",
        "operationId": "listEndpoints",
        "responses": {
          "200": {
            "description": "Endpoint list"
          }
        }
      }
    },
    "/generate": {
      "post": {
        "summary": "Generate a changelog from commit messages",
        "operationId": "generateChangelog",
        "description": "Takes a list of commit messages and generates a formatted changelog. Supports markdown (default), github, slack, and json output formats. Auto-classifies each commit, groups by section, filters user-facing changes, and calculates the required semver bump.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "commits"
                ],
                "properties": {
                  "commits": {
                    "type": "array",
                    "description": "List of commits — strings or objects with message/hash/author",
                    "items": {
                      "oneOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "object",
                          "properties": {
                            "message": {
                              "type": "string"
                            },
                            "hash": {
                              "type": "string"
                            },
                            "author": {
                              "type": "string"
                            },
                            "pr": {
                              "type": "string"
                            }
                          }
                        }
                      ]
                    }
                  },
                  "version": {
                    "type": "string",
                    "description": "Release version label, e.g. '1.4.2' or 'v2.0.0'"
                  },
                  "date": {
                    "type": "string",
                    "description": "Release date (YYYY-MM-DD). Defaults to today."
                  },
                  "format": {
                    "type": "string",
                    "enum": [
                      "markdown",
                      "github",
                      "slack",
                      "json"
                    ],
                    "default": "markdown"
                  },
                  "user_facing_only": {
                    "type": "boolean",
                    "default": false,
                    "description": "Only include user-facing commits (features, fixes, security, etc.)"
                  },
                  "include_authors": {
                    "type": "boolean",
                    "default": false,
                    "description": "Include commit authors in output"
                  },
                  "current_version": {
                    "type": "string",
                    "description": "Current version for semver calculation"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generated changelog",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "changelog": {
                      "type": "string",
                      "description": "Formatted changelog text (null for JSON format)"
                    },
                    "semver": {
                      "type": "object",
                      "properties": {
                        "bump": {
                          "type": "string"
                        },
                        "reason": {
                          "type": "string"
                        },
                        "suggested_version": {
                          "type": "string"
                        }
                      }
                    },
                    "stats": {
                      "type": "object"
                    },
                    "format": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/generate/multi-format": {
      "post": {
        "summary": "Generate changelog in all formats at once",
        "operationId": "generateMultiFormat",
        "description": "Returns the same changelog rendered in all four formats simultaneously: markdown, github, slack, and json. Ideal for pipelines that need to post to multiple destinations in one API call.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "commits"
                ],
                "properties": {
                  "commits": {
                    "type": "array",
                    "items": {}
                  },
                  "version": {
                    "type": "string"
                  },
                  "date": {
                    "type": "string"
                  },
                  "user_facing_only": {
                    "type": "boolean",
                    "default": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "All four formats"
          }
        }
      }
    },
    "/classify": {
      "post": {
        "summary": "Classify commits without generating changelog",
        "operationId": "classifyCommits",
        "description": "Classifies each commit message by type, section, emoji, priority, and whether it is user-facing. Useful for previewing how commits will be categorized before generating a full changelog.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "commits"
                ],
                "properties": {
                  "commits": {
                    "type": "array",
                    "items": {
                      "oneOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "object"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Classified commits"
          }
        }
      }
    },
    "/semver": {
      "post": {
        "summary": "Calculate semver bump from commits",
        "operationId": "calculateSemver",
        "description": "Analyzes commits and returns the required semver bump (major/minor/patch), reason, and optionally the new version number if current_version is provided.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "commits"
                ],
                "properties": {
                  "commits": {
                    "type": "array",
                    "items": {}
                  },
                  "current_version": {
                    "type": "string",
                    "description": "e.g. '1.3.0' — returns suggested new version"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Semver bump result"
          }
        }
      }
    },
    "/parse/git-log": {
      "post": {
        "summary": "Parse raw git log output into commit objects",
        "operationId": "parseGitLog",
        "description": "Converts raw `git log --oneline` output (or plain commit message list) into a structured array of commit objects ready for /generate.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "git_log"
                ],
                "properties": {
                  "git_log": {
                    "type": "string",
                    "description": "Raw output from `git log --oneline` or plain list of commit messages"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Parsed commit objects"
          }
        }
      }
    },
    "/enrich": {
      "post": {
        "summary": "Enrich commits with ticket and PR references",
        "operationId": "enrichCommits",
        "description": "Extracts Jira/Linear ticket IDs (ABC-123), GitHub PR numbers (#42), and other references from commit messages.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "commits"
                ],
                "properties": {
                  "commits": {
                    "type": "array",
                    "items": {}
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Enriched commits with ticket and PR refs"
          }
        }
      }
    },
    "/templates": {
      "get": {
        "summary": "Get example changelog templates",
        "operationId": "getTemplates",
        "responses": {
          "200": {
            "description": "Format templates"
          }
        }
      }
    },
    "/commit-types": {
      "get": {
        "summary": "List all commit type definitions",
        "operationId": "getCommitTypes",
        "responses": {
          "200": {
            "description": "Commit types"
          }
        }
      }
    },
    "/openapi": {
      "get": {
        "summary": "OpenAPI specification",
        "operationId": "getOpenApiSpec",
        "responses": {
          "200": {
            "description": "OpenAPI 3.0 JSON"
          }
        }
      }
    }
  }
}