openapi: 3.0.3
info:
  title: apibuilder generator
  version: 0.12.8
  description: Documentation for an apibuilder code generator API
servers:
- url: http://www.apibuilder.io
paths:
  /_internal_/healthcheck:
    get:
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IoApibuilderGeneratorV0ModelsHealthcheck'
  /generators:
    get:
      description: Get all available generators
      parameters:
      - name: key
        in: query
        description: Filter generators with this key
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: The number of records to return
        required: true
        schema:
          type: integer
          format: int32
      - name: offset
        in: query
        description: Used to paginate. First page of results is 0.
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IoApibuilderGeneratorV0ModelsGenerator'
  /generators/{key}:
    get:
      description: Get generator with this key
      parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IoApibuilderGeneratorV0ModelsGenerator'
        '404':
          description: Not found
  /invocations/{key}:
    post:
      description: Invoke a generator
      parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IoApibuilderGeneratorV0ModelsInvocationForm'
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IoApibuilderGeneratorV0ModelsInvocation'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IoApibuilderGeneratorV0ModelsError'
components:
  schemas:
    IoApibuilderGeneratorV0ModelsInvocationForm:
      description: The invocation form is the payload send to the code generators
        when requesting generation of client code.
      type: object
      required:
      - service
      - attributes
      properties:
        service:
          $ref: '#/components/schemas/IoApibuilderSpecV0ModelsService'
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/IoApibuilderSpecV0ModelsAttribute'
        user_agent:
          type: string
    IoApibuilderGeneratorV0ModelsAttribute:
      description: An attribute represents a key/value pair that is optionally used
        to provide additional instructions / data to the code generator. An example
        could be an attribute to specify the root import path for a go client..
      type: object
      required:
      - name
      - value
      properties:
        name:
          type: string
        value:
          type: string
    IoApibuilderGeneratorV0ModelsHealthcheck:
      type: object
      required:
      - status
      properties:
        status:
          example: healthy
          type: string
    IoApibuilderGeneratorV0ModelsError:
      type: object
      required:
      - code
      - message
      properties:
        code:
          description: Machine readable code for this specific error message
          type: string
        message:
          description: Description of the error
          type: string
    IoApibuilderGeneratorV0ModelsFile:
      description: Represents a source file
      type: object
      required:
      - name
      - contents
      properties:
        name:
          description: The recommended name for the file.
          example: ApiCollectiveApiBuilderApiClient.scala
          type: string
        dir:
          description: The recommended directory path for the file where appropriate.
          example: io/apicollective/apibuilder
          type: string
        contents:
          description: The actual source code.
          type: string
    IoApibuilderGeneratorV0ModelsGenerator:
      description: The generator metadata.
      type: object
      required:
      - key
      - name
      - attributes
      properties:
        key:
          type: string
        name:
          type: string
        language:
          description: A comma separate list of the programming language(s) that this
            generator produces
          example: scala
          type: string
        description:
          type: string
        attributes:
          description: The list of attributes that this code generator can use. You
            can find the full list of available attributes and their descriptions
            at http://apibuilder.io/doc/attributes
          type: array
          items:
            type: string
    IoApibuilderGeneratorV0ModelsInvocation:
      description: The result of invoking a generator.
      type: object
      required:
      - source
      - files
      properties:
        source:
          description: The actual source code.
          deprecated: true
          type: string
        files:
          description: A collection of source files
          type: array
          items:
            $ref: '#/components/schemas/IoApibuilderGeneratorV0ModelsFile'
    IoApibuilderSpecV0ModelsBody:
      type: object
      required:
      - type
      - attributes
      properties:
        type:
          type: string
        description:
          type: string
        deprecation:
          $ref: '#/components/schemas/IoApibuilderSpecV0ModelsDeprecation'
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/IoApibuilderSpecV0ModelsAttribute'
    IoApibuilderSpecV0ModelsModel:
      type: object
      required:
      - name
      - plural
      - fields
      - attributes
      - interfaces
      properties:
        name:
          type: string
        plural:
          type: string
        description:
          type: string
        deprecation:
          $ref: '#/components/schemas/IoApibuilderSpecV0ModelsDeprecation'
        fields:
          type: array
          items:
            $ref: '#/components/schemas/IoApibuilderSpecV0ModelsField'
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/IoApibuilderSpecV0ModelsAttribute'
        interfaces:
          type: array
          items:
            type: string
    IoApibuilderSpecV0ModelsDeprecation:
      description: Indicates that this particular element is considered deprecated
        in the API. See the description for details
      type: object
      properties:
        description:
          type: string
    IoApibuilderSpecV0ModelsField:
      type: object
      required:
      - name
      - type
      - required
      - attributes
      - annotations
      properties:
        name:
          type: string
        type:
          type: string
        description:
          type: string
        deprecation:
          $ref: '#/components/schemas/IoApibuilderSpecV0ModelsDeprecation'
        default:
          type: string
        required:
          type: boolean
        minimum:
          type: integer
          format: int64
        maximum:
          type: integer
          format: int64
        example:
          type: string
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/IoApibuilderSpecV0ModelsAttribute'
        annotations:
          type: array
          items:
            type: string
    IoApibuilderSpecV0ModelsUnion:
      type: object
      required:
      - name
      - plural
      - types
      - attributes
      - interfaces
      properties:
        name:
          type: string
        plural:
          type: string
        discriminator:
          description: If a type discriminator is provided, serialization of these
            union types will always contain a field named with the value of the discriminator
            that will contain the name of the type. This provides a simpler (for many
            use cases) JSON serialization/deserialization mechanism. When specified,
            apibuilder itself will verify that none of the types in the union type
            itself contain a field with the same name as the discriminator
          example: discriminator or type
          type: string
        description:
          type: string
        deprecation:
          $ref: '#/components/schemas/IoApibuilderSpecV0ModelsDeprecation'
        types:
          description: The names of the types that make up this union type
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/IoApibuilderSpecV0ModelsUnionType'
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/IoApibuilderSpecV0ModelsAttribute'
        interfaces:
          type: array
          items:
            type: string
    IoApibuilderSpecV0ModelsAnnotation:
      description: Used to indicate an API concern for a field that is specific to
        the field's usage but not necessarily its data type. For example, you might
        use annotations to mark that certain fields contain PII or PCI data and thus
        should not be stored once processing is complete. Annotations communicate
        meaning to consumers of an API and may also be used within an implementation
        or tooling; for example, using static analysis tools to detect logging of
        sensitive data.
      type: object
      required:
      - name
      properties:
        name:
          type: string
        description:
          type: string
        deprecation:
          $ref: '#/components/schemas/IoApibuilderSpecV0ModelsDeprecation'
    IoApibuilderSpecV0ModelsHeader:
      type: object
      required:
      - name
      - type
      - required
      - attributes
      properties:
        name:
          type: string
        type:
          type: string
        description:
          type: string
        deprecation:
          $ref: '#/components/schemas/IoApibuilderSpecV0ModelsDeprecation'
        required:
          type: boolean
        default:
          type: string
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/IoApibuilderSpecV0ModelsAttribute'
    IoApibuilderSpecV0ModelsOperation:
      type: object
      required:
      - method
      - path
      - parameters
      - responses
      - attributes
      properties:
        method:
          $ref: '#/components/schemas/IoApibuilderSpecV0EnumsMethod'
        path:
          description: The full path to this operation, relative to the service's
            base url.
          type: string
        description:
          type: string
        deprecation:
          $ref: '#/components/schemas/IoApibuilderSpecV0ModelsDeprecation'
        body:
          $ref: '#/components/schemas/IoApibuilderSpecV0ModelsBody'
        parameters:
          type: array
          items:
            $ref: '#/components/schemas/IoApibuilderSpecV0ModelsParameter'
        responses:
          type: array
          items:
            $ref: '#/components/schemas/IoApibuilderSpecV0ModelsResponse'
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/IoApibuilderSpecV0ModelsAttribute'
    IoApibuilderSpecV0ModelsOrganization:
      type: object
      required:
      - key
      properties:
        key:
          description: Unique key identifying the organization that owns this service
          type: string
    IoApibuilderSpecV0ModelsEnumValue:
      type: object
      required:
      - name
      - attributes
      properties:
        name:
          type: string
        description:
          type: string
        deprecation:
          $ref: '#/components/schemas/IoApibuilderSpecV0ModelsDeprecation'
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/IoApibuilderSpecV0ModelsAttribute'
        value:
          description: The actual string representation of this value. If not specified,
            defaults to 'name'
          type: string
    IoApibuilderSpecV0ModelsService:
      type: object
      required:
      - name
      - organization
      - application
      - namespace
      - version
      - info
      - headers
      - imports
      - enums
      - interfaces
      - unions
      - models
      - resources
      - attributes
      - annotations
      properties:
        apidoc:
          $ref: '#/components/schemas/IoApibuilderSpecV0ModelsApidoc'
          description: Documents that this is an apibuilder document, noting the specific
            version used. Internally the version is then used for backwards compatibility
            when applicable as new features are added to apibuilder. Note naming refers
            to the original name of this project, 'apidoc', and is left here to avoid
            a breaking change for preexisting services.
          deprecated: true
        name:
          type: string
        organization:
          $ref: '#/components/schemas/IoApibuilderSpecV0ModelsOrganization'
        application:
          $ref: '#/components/schemas/IoApibuilderSpecV0ModelsApplication'
        namespace:
          description: Fully qualified namespace for this service
          example: io.apibuilder
          type: string
        version:
          example: 1.0.0
          type: string
        base_url:
          type: string
        description:
          type: string
        info:
          $ref: '#/components/schemas/IoApibuilderSpecV0ModelsInfo'
        headers:
          type: array
          items:
            $ref: '#/components/schemas/IoApibuilderSpecV0ModelsHeader'
        imports:
          type: array
          items:
            $ref: '#/components/schemas/IoApibuilderSpecV0ModelsImport'
        enums:
          type: array
          items:
            $ref: '#/components/schemas/IoApibuilderSpecV0ModelsEnum'
        interfaces:
          type: array
          items:
            $ref: '#/components/schemas/IoApibuilderSpecV0ModelsInterface'
        unions:
          type: array
          items:
            $ref: '#/components/schemas/IoApibuilderSpecV0ModelsUnion'
        models:
          type: array
          items:
            $ref: '#/components/schemas/IoApibuilderSpecV0ModelsModel'
        resources:
          type: array
          items:
            $ref: '#/components/schemas/IoApibuilderSpecV0ModelsResource'
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/IoApibuilderSpecV0ModelsAttribute'
        annotations:
          type: array
          items:
            $ref: '#/components/schemas/IoApibuilderSpecV0ModelsAnnotation'
    IoApibuilderSpecV0ModelsResource:
      type: object
      required:
      - type
      - plural
      - operations
      - attributes
      properties:
        type:
          description: The type of this resource will map to a defined model, enum,
            or union type
          type: string
        plural:
          type: string
        path:
          description: The path to this specific resource. This was added in 2016
            to help us differentiate between the resource path and the operation path
            which can be helpful when, for example, generating method names for operations.
            This field is optional as some of our input formats (e.g. swagger) do
            not explicitly differentiate resoure paths.
          type: string
        description:
          type: string
        deprecation:
          $ref: '#/components/schemas/IoApibuilderSpecV0ModelsDeprecation'
        operations:
          type: array
          items:
            $ref: '#/components/schemas/IoApibuilderSpecV0ModelsOperation'
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/IoApibuilderSpecV0ModelsAttribute'
    IoApibuilderSpecV0ModelsEnum:
      type: object
      required:
      - name
      - plural
      - values
      - attributes
      properties:
        name:
          type: string
        plural:
          type: string
        description:
          type: string
        deprecation:
          $ref: '#/components/schemas/IoApibuilderSpecV0ModelsDeprecation'
        values:
          type: array
          items:
            $ref: '#/components/schemas/IoApibuilderSpecV0ModelsEnumValue'
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/IoApibuilderSpecV0ModelsAttribute'
    IoApibuilderSpecV0ModelsLicense:
      description: Describes the software license contact for this service
      type: object
      required:
      - name
      properties:
        name:
          example: MIT
          type: string
        url:
          example: http://opensource.org/licenses/MIT
          type: string
    IoApibuilderSpecV0ModelsApidoc:
      type: object
      required:
      - version
      properties:
        version:
          example: 1.0.3
          type: string
    IoApibuilderSpecV0ModelsImport:
      description: An import is used to declare a dependency on another application.
        This allows you to reference the models and or enums from that application
        in your own app.
      type: object
      required:
      - uri
      - namespace
      - organization
      - application
      - version
      - enums
      - interfaces
      - unions
      - models
      - annotations
      properties:
        uri:
          description: Full URI to the service.json file of the service we are importing
          example: https://www.apibuilder.io/apicollective/apibuilder-spec/0.7.38/service.json
          type: string
        namespace:
          description: the fully qualified namespace that we have imported
          example: io.apibuilder
          type: string
        organization:
          $ref: '#/components/schemas/IoApibuilderSpecV0ModelsOrganization'
        application:
          $ref: '#/components/schemas/IoApibuilderSpecV0ModelsApplication'
        version:
          description: The version of the service that we are importing
          example: 1.0.0
          type: string
        enums:
          description: Enums made available by this import
          type: array
          items:
            type: string
        interfaces:
          description: Interfaces made available by this import
          type: array
          items:
            type: string
        unions:
          description: Unions made available by this import
          type: array
          items:
            type: string
        models:
          description: Models made available by this import
          type: array
          items:
            type: string
        annotations:
          description: Annotations made available by this import
          type: array
          items:
            $ref: '#/components/schemas/IoApibuilderSpecV0ModelsAnnotation'
    IoApibuilderSpecV0ModelsUnionType:
      description: Metadata about one of the types that is part of a union type
      type: object
      required:
      - type
      - attributes
      properties:
        type:
          description: The name of a type (a primitive, model name, or enum name)
            that makes up this union type
          type: string
        description:
          type: string
        deprecation:
          $ref: '#/components/schemas/IoApibuilderSpecV0ModelsDeprecation'
        fields:
          type: array
          items:
            $ref: '#/components/schemas/IoApibuilderSpecV0ModelsField'
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/IoApibuilderSpecV0ModelsAttribute'
        default:
          description: If true, indicates that this type should be used as the default
            when deserializing union types. This field is only used by union types
            that require a discriminator and sets the default value for that discriminator
            during deserialization.
          type: boolean
        discriminator_value:
          description: The discriminator value defines the string to use in the discriminator
            field to identify this type. If not specified, the discriminator value
            will default to the name of the type itself.
          type: string
    IoApibuilderSpecV0ModelsResponse:
      type: object
      required:
      - code
      - type
      properties:
        code:
          $ref: '#/components/schemas/IoApibuilderSpecV0UnionsResponseCode'
        type:
          type: string
        headers:
          type: array
          items:
            $ref: '#/components/schemas/IoApibuilderSpecV0ModelsHeader'
        description:
          type: string
        deprecation:
          $ref: '#/components/schemas/IoApibuilderSpecV0ModelsDeprecation'
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/IoApibuilderSpecV0ModelsAttribute'
    IoApibuilderSpecV0ModelsAttribute:
      description: Represents an additional attribute that is attached to one of the
        objects in apibuilder. The main use case is to capture additional metadata
        that doesn't necessarily define the API but aids in code generation. Examples
        would be hints for certain code generators about classes to extend, interfaces
        to implement, annotations to add, names to assign to certain methods, etc.
        The specific attributes will be applicable only in the context of the specific
        code generators usings them.
      type: object
      required:
      - name
      - value
      properties:
        name:
          type: string
        value:
          type: object
          additionalProperties: true
        description:
          type: string
        deprecation:
          $ref: '#/components/schemas/IoApibuilderSpecV0ModelsDeprecation'
    IoApibuilderSpecV0ModelsParameter:
      type: object
      required:
      - name
      - type
      - location
      - required
      properties:
        name:
          type: string
        type:
          type: string
        location:
          $ref: '#/components/schemas/IoApibuilderSpecV0EnumsParameterLocation'
        description:
          type: string
        deprecation:
          $ref: '#/components/schemas/IoApibuilderSpecV0ModelsDeprecation'
        required:
          type: boolean
        default:
          type: string
        minimum:
          type: integer
          format: int64
        maximum:
          type: integer
          format: int64
        example:
          type: string
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/IoApibuilderSpecV0ModelsAttribute'
    IoApibuilderSpecV0ModelsInfo:
      description: General metadata about this service
      type: object
      properties:
        license:
          $ref: '#/components/schemas/IoApibuilderSpecV0ModelsLicense'
        contact:
          $ref: '#/components/schemas/IoApibuilderSpecV0ModelsContact'
    IoApibuilderSpecV0ModelsApplication:
      type: object
      required:
      - key
      properties:
        key:
          description: Unique key identifying this application
          type: string
    IoApibuilderSpecV0ModelsContact:
      description: Describes the primary contact for this service
      type: object
      properties:
        name:
          example: Michael Bryzek
          type: string
        url:
          example: https://www.apibuilder.io
          type: string
        email:
          example: michael@test.apibuilder.io
          type: string
    IoApibuilderSpecV0ModelsInterface:
      type: object
      required:
      - name
      - plural
      - fields
      - attributes
      properties:
        name:
          type: string
        plural:
          type: string
        description:
          type: string
        deprecation:
          $ref: '#/components/schemas/IoApibuilderSpecV0ModelsDeprecation'
        fields:
          type: array
          items:
            $ref: '#/components/schemas/IoApibuilderSpecV0ModelsField'
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/IoApibuilderSpecV0ModelsAttribute'
    IoApibuilderSpecV0EnumsParameterLocation:
      type: string
      enum:
      - Path
      - Query
      - Form
      - Header
    IoApibuilderSpecV0EnumsResponseCodeOption:
      type: string
      enum:
      - Default
    IoApibuilderSpecV0EnumsMethod:
      type: string
      enum:
      - GET
      - POST
      - PUT
      - PATCH
      - DELETE
      - HEAD
      - CONNECT
      - OPTIONS
      - TRACE
    IoApibuilderSpecV0UnionsResponseCode:
      oneOf:
      - $ref: '#/components/schemas/Integer'
      - $ref: '#/components/schemas/IoApibuilderSpecV0EnumsResponseCodeOption'
