openapi: 3.0.0
servers:
  # Added by API Auto Mocking Plugin
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/JohnGoyette/intraoral-exposure-service/1.0
info:
  description: >
    The Intraoral Exposure API provides exposure data for intraoral dental imaging applications. The API can be used to retrieve information about an intraoral exposure from an Intraoral X-ray Tube Generator so that the exposure data can be stored along with the patient's media and dental records.


    A service that implements the Intraoral Exposure API manages one or more Intraoral X-ray Tube Generators. API calls associated with `generators` may be used to retrieve information about the Intraoral X-ray Tube generators that the service manages. API calls associated with `exposures` may be used to retrieve exposure data from a give generator.

  version: "1.0"
  title: Intraoral Exposure API
  contact:
    email: John.Goyette@dentsplysirona.com
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'

security:
  - ApiKeyAuth: []

tags:
  - name: Generators
    description: Intraoral X-ray tube generators
  - name: Exposures
    description: Exposure data from generators
paths:
  /generator:
    get:
      tags:
        - Generators
      summary: retrieve all generators
      operationId: getAllGenerators
      description: |
        Retrieves a list of all available Intraoral X-ray Tube Generators
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Generator'
  /generator/{id}:
    get:
      tags:
        - Generators
      summary: retrieve a generator
      operationId: getGenerator
      description: |
        Retrieves information about an Intraoral X-ray Tube Generator
      parameters:
        - name: id
          in: path
          required: true
          description: The Id of the generator
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Generator'
        '404':
          description: Generator not found

  /generator/{id}/exposure:
    get:
      tags:
        - Exposures
      summary: retrieve exposures
      operationId: getExposures
      description: |
        Retrieves exposures from an Intraoral X-ray Tube Generator sorted in chronological order starting with the most recent exposure. The results can be paginated and filtered by using the optional query parameters.
      parameters:
        - name: id
          in: path
          required: true
          description: The Id of the generator
          schema:
            type: string
        - in: query
          name: skip
          description: Number of exposures to skip for pagination
          schema:
            type: integer
            format: int32
            minimum: 0
        - in: query
          name: limit
          description: Maximum number of exposures to return for pagination
          schema:
            type: integer
            format: int32
            minimum: 0
            maximum: 50
        - in: query
          name: startTime
          description: Local timestamp of the oldest exposure that should be returned.
          schema:
            type: string
            format: date-time
        - in: query
          name: endTime
          description: Local timestamp of the newest exposure that should be returned
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    format: int32
                    example: 125
                    description: Total exposures available from the query results
                  skip:
                    type: integer
                    format: int32
                    example: 0
                    description: Number of exposures skipped in the returned exposures array
                  limit:
                    type: integer
                    format: int32
                    example: 50
                    description: Maximum number of exposures in the returned exposures array
                  exposures:
                    type: array
                    description: The returned set of exposures after filtering and pagination
                    items:
                      $ref: '#/components/schemas/Exposure'
        '400':
          description: Bad request or invalid search parameters
        '404':
          description: Generator not found
  /generator/{id}/exposure/{exposureId}:
    get:
      tags:
        - Exposures
      summary: retrieve an exposure
      operationId: getExposure
      description: |
        Retrieves a specific exposure from an Intraoral X-ray Tube Generator
      parameters:
        - name: id
          in: path
          required: true
          description: The Id of the generator
          schema:
            type: string
        - name: exposureId
          in: path
          required: true
          description: The Id of the exposure
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Exposure'
        '404':
          description: Generator or Exposure not found

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

  schemas:
    Generator:
      type: object
      required:
        - id
        - name
        - manufacturer
        - model
        - serialNumber
      properties:
        id:
          type: string
          format: uuid
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
          description: Unique Id assigned to this generator
        name:
          type: string
          example: Operatory 1
          description: A friendly name used to refer this generator
        manufacturer:
          type: string
          example: Dentsply Sirona
          description: Manufacturer of the generator
        model:
          type: string
          example: Heliodent
          description: Model name of the generator
        serialNumber:
          type: string
          example: HS-123456789
          description: Serial number of the generator
    Exposure:
      type: object
      required:
        - id
        - recordedTime
        - kiloVolts
        - milliAmps
        - exposureTime
      properties:
        id:
          type: string
          format: uuid
          example: 006906f2-9592-11ec-b909-0242ac120002
          description: Unique Id assigned to this exposure
        recordedTime:
          type: string
          format: date-time
          example: '2016-08-29T09:12:33.000-05:00'
          description: Timestamp representing the date and time expressed in local time that the exposure was recorded
        kiloVolts:
          type: number
          format: integer
          example: 60
          description: X-ray tube voltage in killovolts (kV)
        milliAmps:
          type: number
          format: integer
          example: 7
          description: X-ray tube amperage in milliamps (mA)
        exposureTime:
          type: number
          format: float
          example: 120.0
          description: X-ray exposure time in milliseconds (mS)
        doseAreaProduct:
          type: number
          format: float
          example: 1.15
          description: The dose area product (DAP) of this exposure in decigray centimeters squared (dGy*cm<sup>2</sup>)
        tubeLength:
          type: number
          format: float
          example: 20
          description: Length of the collimator tube in centimeters (cm)
        jawRegion:
          type: string
          enum: [ mandible, maxilla ]
          example: mandible
          description: The region in the jaw that was exposed
        toothRegion:
          type: string
          enum: [ incisor, canine, premolar, molar ]
          example: molar
          description: The type of tooth that was exposed
        patientSize:
          type: string
          enum: [ child, adult ]
          example: adult
          description: Relative size/age of the patient
        imageType:
          type: string
          enum: [ periapical, bitewing, occlusal ]
          example: bitewing
          description: The type of intraoral exposure