openapi: 3.1.0
info:
  title: Spring Cloud Config Server API
  description: >-
    Spring Cloud Config Server provides HTTP resource-based API for external
    configuration. It serves property sources for applications organized by
    application name, profile, and label (git branch/tag). Supports JSON,
    YAML, and properties formats.
  version: 4.1.0
  contact:
    name: Spring Cloud
    url: https://spring.io/projects/spring-cloud-config
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: http://localhost:8888
    description: Local Config Server
  - url: http://{config_host}:{port}
    description: Custom Config Server
    variables:
      config_host:
        default: localhost
      port:
        default: '8888'
security:
  - BasicAuth: []
  - BearerAuth: []
paths:
  /{application}/{profile}:
    get:
      operationId: getEnvironment
      summary: Get environment configuration
      description: >-
        Returns the Environment object containing property sources for the given
        application and profile. Uses the default label (usually master/main).
      tags:
        - Configuration
      parameters:
        - name: application
          in: path
          required: true
          schema:
            type: string
          description: Application name
        - name: profile
          in: path
          required: true
          schema:
            type: string
          description: Active profile(s), comma-separated
      responses:
        '200':
          description: Environment configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Environment'
  /{application}/{profile}/{label}:
    get:
      operationId: getEnvironmentWithLabel
      summary: Get environment configuration with label
      description: >-
        Returns the Environment for the given application, profile, and label.
        Label typically corresponds to a git branch, tag, or commit hash.
      tags:
        - Configuration
      parameters:
        - name: application
          in: path
          required: true
          schema:
            type: string
          description: Application name
        - name: profile
          in: path
          required: true
          schema:
            type: string
          description: Active profile(s), comma-separated
        - name: label
          in: path
          required: true
          schema:
            type: string
          description: Branch, tag, or commit hash
      responses:
        '200':
          description: Environment configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Environment'
  /{application}-{profile}.yml:
    get:
      operationId: getConfigYaml
      summary: Get configuration as YAML
      description: Returns the configuration as a YAML document.
      tags:
        - Configuration
      parameters:
        - name: application
          in: path
          required: true
          schema:
            type: string
        - name: profile
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: YAML configuration
          content:
            application/x-yaml:
              schema:
                type: string
            text/yaml:
              schema:
                type: string
  /{application}-{profile}.properties:
    get:
      operationId: getConfigProperties
      summary: Get configuration as properties
      description: Returns the configuration as a Java properties file.
      tags:
        - Configuration
      parameters:
        - name: application
          in: path
          required: true
          schema:
            type: string
        - name: profile
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Properties configuration
          content:
            text/plain:
              schema:
                type: string
  /{application}-{profile}.json:
    get:
      operationId: getConfigJson
      summary: Get configuration as JSON
      description: Returns the configuration as a JSON document.
      tags:
        - Configuration
      parameters:
        - name: application
          in: path
          required: true
          schema:
            type: string
        - name: profile
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: JSON configuration
          content:
            application/json:
              schema:
                type: object
  /{label}/{application}-{profile}.yml:
    get:
      operationId: getConfigYamlWithLabel
      summary: Get configuration as YAML with label
      description: Returns YAML configuration for a specific label (branch/tag).
      tags:
        - Configuration
      parameters:
        - name: label
          in: path
          required: true
          schema:
            type: string
        - name: application
          in: path
          required: true
          schema:
            type: string
        - name: profile
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: YAML configuration
          content:
            application/x-yaml:
              schema:
                type: string
  /{label}/{application}-{profile}.properties:
    get:
      operationId: getConfigPropertiesWithLabel
      summary: Get configuration as properties with label
      description: Returns properties configuration for a specific label.
      tags:
        - Configuration
      parameters:
        - name: label
          in: path
          required: true
          schema:
            type: string
        - name: application
          in: path
          required: true
          schema:
            type: string
        - name: profile
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Properties configuration
          content:
            text/plain:
              schema:
                type: string
  /{label}/{application}-{profile}.json:
    get:
      operationId: getConfigJsonWithLabel
      summary: Get configuration as JSON with label
      description: Returns JSON configuration for a specific label.
      tags:
        - Configuration
      parameters:
        - name: label
          in: path
          required: true
          schema:
            type: string
        - name: application
          in: path
          required: true
          schema:
            type: string
        - name: profile
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: JSON configuration
          content:
            application/json:
              schema:
                type: object
  /{application}/{profile}/{label}/{path}:
    get:
      operationId: getResourceFile
      summary: Get a resource file
      description: >-
        Serves a plain text resource file from the configuration repository
        (e.g., nginx.conf, logback.xml). The path is resolved relative to the
        repository root for the specified label.
      tags:
        - Resources
      parameters:
        - name: application
          in: path
          required: true
          schema:
            type: string
        - name: profile
          in: path
          required: true
          schema:
            type: string
        - name: label
          in: path
          required: true
          schema:
            type: string
        - name: path
          in: path
          required: true
          schema:
            type: string
          description: Path to the resource file in the repository
      responses:
        '200':
          description: Resource file content
          content:
            text/plain:
              schema:
                type: string
            application/octet-stream:
              schema:
                type: string
                format: binary
        '404':
          description: Resource not found
  /encrypt:
    post:
      operationId: encrypt
      summary: Encrypt a value
      description: >-
        Encrypts a plain text value using the server's configured encryption key.
        Requires spring.cloud.config.server.encrypt.enabled=true.
      tags:
        - Encryption
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: string
      responses:
        '200':
          description: Encrypted value
          content:
            text/plain:
              schema:
                type: string
        '404':
          description: Encryption key not configured
  /decrypt:
    post:
      operationId: decrypt
      summary: Decrypt a value
      description: Decrypts a cipher text value using the server's configured encryption key.
      tags:
        - Encryption
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: string
      responses:
        '200':
          description: Decrypted value
          content:
            text/plain:
              schema:
                type: string
        '404':
          description: Encryption key not configured
  /encrypt/status:
    get:
      operationId: encryptionStatus
      summary: Check encryption status
      description: Returns the status of the encryption configuration.
      tags:
        - Encryption
      responses:
        '200':
          description: Encryption status
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - OK
                      - NO_KEY
  /monitor:
    post:
      operationId: triggerRefresh
      summary: Trigger configuration refresh notification
      description: >-
        Accepts webhook notifications from git hosting providers (GitHub,
        GitLab, Bitbucket) and triggers a Spring Cloud Bus refresh event.
      tags:
        - Monitoring
      parameters:
        - name: path
          in: query
          schema:
            type: string
          description: File path pattern to match
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Refresh notification accepted
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                description: List of applications to refresh
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    BearerAuth:
      type: http
      scheme: bearer
  schemas:
    Environment:
      type: object
      properties:
        name:
          type: string
          description: Application name
        profiles:
          type: array
          items:
            type: string
          description: Active profiles
        label:
          type: string
          description: Label (branch/tag)
          nullable: true
        version:
          type: string
          description: Git commit hash or version identifier
          nullable: true
        state:
          type: string
          nullable: true
        propertySources:
          type: array
          items:
            $ref: '#/components/schemas/PropertySource'
    PropertySource:
      type: object
      properties:
        name:
          type: string
          description: >-
            Source identifier (e.g., git URL + path)
        source:
          type: object
          additionalProperties: true
          description: Key-value configuration properties
tags:
  - name: Configuration
    description: Fetch application configuration
  - name: Resources
    description: Fetch resource files from the config repository
  - name: Encryption
    description: Encrypt and decrypt configuration values
  - name: Monitoring
    description: Webhook and monitoring endpoints