openapi: 3.1.0
info:
  title: Spring Initializr API
  description: >-
    The Spring Initializr REST API enables programmatic generation of Spring Boot
    project scaffolding. It provides endpoints to discover available dependencies,
    project types, Spring Boot versions, and packaging options, as well as generating
    ready-to-use project archives in zip or tar.gz format. The API is used by IDEs
    (IntelliJ IDEA, Eclipse Spring Tools Suite, VS Code Spring Boot Extension),
    CLI tools (Spring CLI), and custom tooling to bootstrap new Spring Boot projects.
  version: '1.0'
  contact:
    name: Spring Team
    url: https://spring.io/team
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
externalDocs:
  description: Spring Initializr Reference Documentation
  url: https://docs.spring.io/initializr/docs/current/reference/html/
servers:
  - url: https://start.spring.io
    description: Official Spring Initializr Service
tags:
  - name: Project Generation
    description: Generate new Spring Boot project archives
  - name: Metadata
    description: Discover available project options and capabilities
security: []
paths:
  /starter.zip:
    get:
      operationId: generateProjectZip
      summary: Generate Project ZIP
      description: >-
        Generates a new Spring Boot project and returns it as a ZIP archive.
        Specify the project group, artifact, dependencies, Java version, Spring Boot
        version, and other options via query parameters.
      tags:
        - Project Generation
      parameters:
        - $ref: '#/components/parameters/type'
        - $ref: '#/components/parameters/language'
        - $ref: '#/components/parameters/bootVersion'
        - $ref: '#/components/parameters/baseDir'
        - $ref: '#/components/parameters/groupId'
        - $ref: '#/components/parameters/artifactId'
        - $ref: '#/components/parameters/name'
        - $ref: '#/components/parameters/description'
        - $ref: '#/components/parameters/packageName'
        - $ref: '#/components/parameters/packaging'
        - $ref: '#/components/parameters/javaVersion'
        - $ref: '#/components/parameters/dependencies'
      responses:
        '200':
          description: ZIP archive of the generated project
          content:
            application/zip:
              schema:
                type: string
                format: binary
  /starter.tgz:
    get:
      operationId: generateProjectTgz
      summary: Generate Project TGZ
      description: >-
        Generates a new Spring Boot project and returns it as a tar.gz archive.
        Accepts the same query parameters as the ZIP endpoint.
      tags:
        - Project Generation
      parameters:
        - $ref: '#/components/parameters/type'
        - $ref: '#/components/parameters/language'
        - $ref: '#/components/parameters/bootVersion'
        - $ref: '#/components/parameters/baseDir'
        - $ref: '#/components/parameters/groupId'
        - $ref: '#/components/parameters/artifactId'
        - $ref: '#/components/parameters/name'
        - $ref: '#/components/parameters/description'
        - $ref: '#/components/parameters/packageName'
        - $ref: '#/components/parameters/packaging'
        - $ref: '#/components/parameters/javaVersion'
        - $ref: '#/components/parameters/dependencies'
      responses:
        '200':
          description: TGZ archive of the generated project
          content:
            application/x-tar:
              schema:
                type: string
                format: binary
  /:
    get:
      operationId: getMetadata
      summary: Get Initializr Metadata
      description: >-
        Returns the full metadata document describing all available project
        types, Spring Boot versions, dependencies, languages, Java versions,
        packaging options, and their defaults. Clients use this to present
        choices to the user before generating a project.
      tags:
        - Metadata
      responses:
        '200':
          description: Spring Initializr metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitializrMetadata'
            application/vnd.initializr.v2.2+json:
              schema:
                $ref: '#/components/schemas/InitializrMetadata'
  /dependencies:
    get:
      operationId: getDependencies
      summary: Get Available Dependencies
      description: >-
        Returns the list of available Spring Boot starter dependencies that can
        be added to a generated project. Results can be filtered by Spring Boot
        version compatibility.
      tags:
        - Metadata
      parameters:
        - name: bootVersion
          in: query
          required: false
          description: Filter dependencies by Spring Boot version compatibility
          schema:
            type: string
          example: 3.4.5
      responses:
        '200':
          description: Available dependencies
          content:
            application/vnd.initializr.v2.2+json:
              schema:
                $ref: '#/components/schemas/DependenciesResponse'
components:
  parameters:
    type:
      name: type
      in: query
      required: false
      description: Project type (build system)
      schema:
        type: string
        enum:
          - maven-project
          - gradle-project
          - gradle-project-kotlin
        default: maven-project
    language:
      name: language
      in: query
      required: false
      description: Programming language
      schema:
        type: string
        enum:
          - java
          - kotlin
          - groovy
        default: java
    bootVersion:
      name: bootVersion
      in: query
      required: false
      description: Spring Boot version
      schema:
        type: string
      example: 3.4.5
    baseDir:
      name: baseDir
      in: query
      required: false
      description: Base directory for the generated project archive
      schema:
        type: string
      example: demo
    groupId:
      name: groupId
      in: query
      required: false
      description: Maven group ID
      schema:
        type: string
        default: com.example
    artifactId:
      name: artifactId
      in: query
      required: false
      description: Maven artifact ID / project name
      schema:
        type: string
        default: demo
    name:
      name: name
      in: query
      required: false
      description: Project name
      schema:
        type: string
        default: demo
    description:
      name: description
      in: query
      required: false
      description: Project description
      schema:
        type: string
        default: Demo project for Spring Boot
    packageName:
      name: packageName
      in: query
      required: false
      description: Root Java package name
      schema:
        type: string
        default: com.example.demo
    packaging:
      name: packaging
      in: query
      required: false
      description: Packaging type
      schema:
        type: string
        enum:
          - jar
          - war
        default: jar
    javaVersion:
      name: javaVersion
      in: query
      required: false
      description: Java version
      schema:
        type: string
        enum:
          - '21'
          - '17'
          - '11'
        default: '21'
    dependencies:
      name: dependencies
      in: query
      required: false
      description: >-
        Comma-separated list of dependency IDs to include
        (e.g., web,data-jpa,security,actuator)
      schema:
        type: string
      example: 'web,data-jpa,security,actuator,lombok'
  schemas:
    InitializrMetadata:
      type: object
      description: Full Spring Initializr capabilities metadata
      properties:
        dependencies:
          type: object
          description: Available dependencies grouped by category
          properties:
            type:
              type: string
              example: hierarchical-multi-select
            values:
              type: array
              items:
                $ref: '#/components/schemas/DependencyGroup'
        type:
          type: object
          description: Project type options
          properties:
            type:
              type: string
            default:
              type: string
            values:
              type: array
              items:
                $ref: '#/components/schemas/MetadataOption'
        bootVersion:
          type: object
          properties:
            type:
              type: string
            default:
              type: string
            values:
              type: array
              items:
                $ref: '#/components/schemas/MetadataOption'
        packaging:
          type: object
          properties:
            type:
              type: string
            default:
              type: string
            values:
              type: array
              items:
                $ref: '#/components/schemas/MetadataOption'
        javaVersion:
          type: object
          properties:
            type:
              type: string
            default:
              type: string
            values:
              type: array
              items:
                $ref: '#/components/schemas/MetadataOption'
        language:
          type: object
          properties:
            type:
              type: string
            default:
              type: string
            values:
              type: array
              items:
                $ref: '#/components/schemas/MetadataOption'
    DependencyGroup:
      type: object
      properties:
        name:
          type: string
          example: Web
        values:
          type: array
          items:
            $ref: '#/components/schemas/Dependency'
    Dependency:
      type: object
      properties:
        id:
          type: string
          example: web
        name:
          type: string
          example: Spring Web
        description:
          type: string
          example: Build web, including RESTful, applications using Spring MVC.
        compatibilityRange:
          type: string
          example: '[3.0.0,4.0.0-M1)'
    MetadataOption:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        default:
          type: boolean
    DependenciesResponse:
      type: object
      properties:
        bootVersion:
          type: string
          example: 3.4.5
        dependencies:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Dependency'