swagger.yaml

openapi: 3.1.0
info:
  title: EV Backend
  description: Backend of the EV written in Go.
  version: 1.0.0
servers:
  - url: http://ev.localhost
  - url: http://localhost:8080
tags:
  - name: Discovery
    description: Endpoints related to discover relevant information.
  - name: Authorization
    description: Endpoints related to the OAuth Authorization Flow.
paths:
  /emsps:
    get:
      tags:
        - Discovery
      summary: Gets supported eMSPs
      description: Returns an array of supported eMSP infos.
      operationId: getEmsps
      responses:
        "200":
          description: List of eMSPs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Emsp'
                x-content-type: application/json
        "500":
          description: Internal server error
  /cpr:
    post:
      tags:
        - Authorization
      summary: Receives Contract Provisioning Request which initializes the authorization flow
      description: Transfers the desired eMSP and authorization parameters.
      operationId: requestContractProvisioning
      requestBody:
        $ref: '#/components/requestBodies/ContractProvisioningRequest'
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractProvisioningResponse'
        "400":
          description: Bad request
        "404":
          description: eMSP ID not found
        "500":
          description: Internal server error
  # /confirm:
  #   post:
  #     tags:
  #       - Authorization
  #     summary: Finishes the authorization
  #     description: Transfers the Authorization Code to the EV which finishes the authorization process.
  #     operationId: confirmAuthorization
  #     requestBody:
  #       $ref: '#/components/requestBodies/ConfirmationRequest'
  #     responses:
  #       "200":
  #         description: OK
  #       "404":
  #         description: Unknown state
  #       "500":
  #         description: Internal server error
components:
  schemas:
    Emsp:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/EmspId'
        name:
          type: string
          example: Example eMSP
        base_url:
          type: string
          format: uri
          example: https://authorization-server.example.com/
        image:
          type: string
          format: uri
          example: assets/example.svg
      required:
        - id
        - name
        - base_url
    EmspId:
      type: string
      example: sample_emsp
    ContractProvisioningRequest:
      type: object
      properties:
        emsp_id:
          $ref: '#/components/schemas/EmspId'
        authorization_detail:
          $ref: '#/components/schemas/AuthorizationDetail'
      required:
        - emsp_id
        - authorization_detail
    AuthorizationDetail:
      type: object
      properties:
        type:
          type: string
          example: "pnc_contract_request"
        charging_period:
          $ref: '#/components/schemas/ChargingPeriod'
        maximum_amount:
          $ref: '#/components/schemas/CurrencyAmount'
        maximum_transaction_amount:
          $ref: '#/components/schemas/CurrencyAmount'
      required:
        - type
        - charging_period
        - maximum_amount
        - maximum_transaction_amount
    ChargingPeriod:
      type: object
      properties:
        start:
          type: string
          format: date-time
          example: 2023-09-07T14:00:00Z
        end:
          type: string
          format: date-time
          example: 2023-10-07T15:00:00Z
      required:
        - start
        - end
    CurrencyAmount:
      type: object
      properties:
        amount:
          type: string
          format: decimal
          example: "123.50"
        currency:
          $ref: '#/components/schemas/Currencies'
      required:
        - amount
        - currency
    Currencies:
      type: string
      enum:
       - EUR
       - USD
      example: EUR
    ContractProvisioningResponse:
      type: object
      properties:
        user_code:
          $ref: '#/components/schemas/UserCode'
        verification_uri:
          $ref: '#/components/schemas/VerificationUri'
      required:
        - user_code
        - verification_uri
    UserCode:
      type: string
      example: A1B2C3
    VerificationUri:
      type: string
      format: url
      example: https://authorization-server.example.com/verify
    # ConfirmationRequest:
    #   type: object
    #   properties:
    #     auth_code:
    #       type: string
    #       example: LRS7CLedX3ws5fiJO4KenKe
    #   required:
    #     - auth_code
  requestBodies:
    ContractProvisioningRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ContractProvisioningRequest'
    ConfirmationRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ConfirmationRequest'