express-gateway/lib/rest/swagger-doc.yaml

A microservices API gateway built on top of ExpressJS

---
openapi: 3.0.0
servers:
- url: '/'
info:
  version: 1.0.0
  title: Express Gateway Admin API
  description: Express Gateway Admin API
  contact:
    name: Express Gateway
    url: https://express-gateway.io
    email: api@express-gateway.io
  license:
    name: Apache License 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
paths:
  '/users':
    get:
      tags:
      - Users
      summary: Returns all users from Express Gateway
      description: Users
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                '$ref': '#/components/schemas/Users'
    post:
      tags:
      - Users
      summary: Creates new User
      responses:
        '201':
          description: Created
          content:
            'application/json':
              schema:
                '$ref': '#/components/schemas/User'
      requestBody:
        content:
          application/json:
            schema:
              '$ref': '#/components/schemas/CreateUserRequest'
        description: user to add to the system
        required: true
  '/users/{usernameOrId}':
    parameters:
    - name: usernameOrId
      in: path
      required: true
      description: username or user id
      schema:
        type: string
    get:
      tags:
      - Users
      summary: Returns a user by id or username
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                '$ref': '#/components/schemas/User'
        '404':
          '$ref': '#/components/responses/NotFound'
    delete:
      tags:
      - Users
      summary: Deletes a user by id or username
      responses:
        '204':
          description: No Content
        '404':
          '$ref': '#/components/responses/NotFound'
    put:
      tags:
      - Users
      summary: Updates a user by id or username
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                '$ref': '#/components/schemas/User'
        '404':
          '$ref': '#/components/responses/NotFound'
        '422':
          '$ref': '#/components/responses/ValidationError'
      requestBody:
        content:
          application/json:
            schema:
              '$ref': '#/components/schemas/UpdateUserRequest'
        description: user to add to the system
        required: true
  '/users/{id}/status':
    put:
      tags:
      - Users
      summary: Updates Active\NonActive status by username or id
      parameters:
      - name: id
        in: path
        required: true
        description: username or id of user
        schema:
          type: string
      responses:
        '200':
          '$ref': '#/components/responses/StatusUpdateResponse'
        '404':
          '$ref': '#/components/responses/NotFound'
      requestBody:
        '$ref': '#/components/requestBodies/Status'
  '/apps':
    get:
      tags:
      - Apps
      summary: Returns all Apps from Express Gateway
      description: Users
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                '$ref': '#/components/schemas/Apps'
    post:
      tags:
      - Apps
      summary: Creates new App
      responses:
        '201':
          description: Created
          content:
            'application/json':
              schema:
                '$ref': '#/components/schemas/App'
      requestBody:
        content:
          application/json:
            schema:
              '$ref': '#/components/schemas/CreateAppRequest'
        description: user to add to the system
        required: true
  '/apps/{appId}':
    parameters:
    - name: appId
      in: path
      required: true
      description: application id
      schema:
        type: string
    get:
      tags:
      - Apps
      summary: Returns an app by id
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                '$ref': '#/components/schemas/App'
        '404':
          '$ref': '#/components/responses/NotFound'
    delete:
      tags:
      - Apps
      summary: Deletes an app by id
      responses:
        '204':
          description: No Content
        '404':
          '$ref': '#/components/responses/NotFound'
    put:
      tags:
      - Apps
      summary: Updates an app by id
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                '$ref': '#/components/schemas/App'
        '404':
          '$ref': '#/components/responses/NotFound'
        '422':
          '$ref': '#/components/responses/ValidationError'
      requestBody:
        content:
          application/json:
            schema:
              '$ref': '#/components/schemas/UpdateAppRequest'
        description: App to add to the system
        required: true
  '/apps/{appId}/status':
    put:
      tags:
      - Apps
      summary: Updates Active\NonActive status by app id
      parameters:
      - name: appId
        in: path
        required: true
        description: application id
        schema:
          type: string
      responses:
        '200':
          '$ref': '#/components/responses/StatusUpdateResponse'
        '404':
          '$ref': '#/components/responses/NotFound'
      requestBody:
        '$ref': '#/components/requestBodies/Status'
  '/credentials':
    post:
      tags:
      - Credentials
      summary: Create Credential
      responses:
        '201':
          description: Created
          content:
            'application/json':
              schema:
                '$ref': '#/components/schemas/Credential'
      requestBody:
        content:
          application/json:
            schema:
              '$ref': '#/components/schemas/CreateCredentialRequest'
  '/credentials/{consumerId}':
    get:
      tags:
      - Credentials
      summary: Get all Credentials for consumer
      parameters:
      - name: consumerId
        in: path
        required: true
        description: Username or UserId or AppId
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                '$ref': '#/components/schemas/Credentials'
  '/credentials/{type}/{credentialId}/status':
    put:
      tags:
      - Credentials
      summary: Updates Active\Inactive status by credential id
      parameters:
      - name: credentialId
        in: path
        required: true
        description: for key-auth this is keyId, for basic-auth and oauth2 this is
          AppId or UserId or Username
        schema:
          type: string
      - name: type
        in: path
        required: true
        description: type of credential
        schema:
          type: string
          enum:
          - key-auth
          - basic-auth
          - oauth2
      responses:
        '200':
          '$ref': '#/components/responses/StatusUpdateResponse'
        '404':
          '$ref': '#/components/responses/NotFound'
      requestBody:
        '$ref': '#/components/requestBodies/Status'
  '/credentials/{type}/{credentialId}':
    get:
      tags:
      - Credentials
      summary: Get Credential by credential id
      parameters:
      - name: credentialId
        in: path
        required: true
        description: for key-auth this is keyId, for basic-auth and oauth2 this is
          AppId or UserId or Username
        schema:
          type: string
      - name: type
        in: path
        required: true
        description: type of credential
        schema:
          type: string
          enum:
          - key-auth
          - basic-auth
          - oauth2
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                '$ref': '#/components/schemas/Credential'
        '404':
          '$ref': '#/components/responses/NotFound'
  '/credentials/{type}/{credentialId}/scopes':
    put:
      tags:
      - Credentials
      summary: Set scopes for Credential
      parameters:
      - name: credentialId
        in: path
        required: true
        description: for key-auth this is keyId, for basic-auth and oauth2 this is
          AppId or UserId or Username
        schema:
          type: string
      - name: type
        in: path
        required: true
        description: type of credential
        schema:
          type: string
          enum:
          - key-auth
          - basic-auth
          - oauth2
      responses:
        '204':
          description: No Content
        '404':
          '$ref': '#/components/responses/NotFound'
      requestBody:
        content:
          application/json:
            schema:
              '$ref': '#/components/schemas/Scopes'
  '/credentials/{type}/{credentialId}/scopes/{scope}':
    parameters:
    - name: credentialId
      in: path
      required: true
      description: for key-auth this is keyId, for basic-auth and oauth2 this is AppId
        or UserId or Username
      schema:
        type: string
    - name: type
      in: path
      required: true
      description: type of credential
      schema:
        type: string
        enum:
        - key-auth
        - basic-auth
        - oauth2
    - name: scope
      in: path
      required: true
      description: scope name
      schema:
        type: string
    put:
      tags:
      - Credentials
      summary: Add single scope to Credential scopes
      responses:
        '204':
          description: No Content
        '404':
          '$ref': '#/components/responses/NotFound'
    delete:
      tags:
      - Credentials
      summary: Remove single scope from Credential scopes
      responses:
        '204':
          description: No Content
        '404':
          '$ref': '#/components/responses/NotFound'
  '/scopes':
    get:
      tags:
      - Scopes
      summary: Get all scopes in Express Gateway
      responses:
        '200':
          description: Scopes
          content:
            'application/json':
              schema:
                '$ref': '#/components/schemas/Scopes'
    post:
      tags:
      - Scopes
      summary: Create scopes in Express Gateway
      responses:
        '201':
          description: Scopes
          content:
            'application/json':
              schema:
                '$ref': '#/components/schemas/Scopes'
      requestBody:
        content:
          application/json:
            schema:
              '$ref': '#/components/schemas/Scopes'
        description: status
  '/scopes/{scope}':
    parameters:
    - name: scope
      in: path
      required: true
      description: scope name
      schema:
        type: string
    put:
      tags:
      - Scopes
      summary: Creates a scope in Express Gateway, so it can be referenced in credentials
      responses:
        '201':
          description: Created
        '409':
          '$ref': '#/components/responses/EntityExists'
    delete:
      tags:
      - Scopes
      summary: Remove a scope from Express Gateway
      responses:
        '204':
          description: No Content
        '404':
          '$ref': '#/components/responses/NotFound'
    get:
      tags:
      - Scopes
      summary: Get scope by name (check exists)
      responses:
        '200':
          description: Scope
          content:
            'application/json':
              schema:
                type: object
                properties:
                  scope:
                    '$ref': '#/components/schemas/Scope'
        '404':
          '$ref': '#/components/responses/NotFound'
  '/plugins':
    get:
      tags:
      - Plugins
      summary: Returns a list of installed plugins
      description: Currently an experimental feature activated using the `--experimental-plugins-api` flag.
      responses:
        '200':
          description: Plugins
          content:
            'application/json':
              schema:
                '$ref': '#/components/schemas/Plugins'
    post:
      tags:
      - Plugins
      summary: Install Plugin
      description: Currently an experimental feature activated using the `--experimental-plugins-api` flag.
      responses:
        '201':
          description: Created
          content:
            'application/json':
              schema:
                '$ref': '#/components/schemas/PluginInstallResponse'
      requestBody:
        content:
          'application/json':
            schema:
              type: object
              properties:
                package:
                  type: string
              example:
                package: eg-example-plugin
  '/plugins/{pluginName}':
    get:
      tags:
      - Plugins
      summary: Return a single plugin
      description: Currently an experimental feature activated using the `--experimental-plugins-api` flag.
      responses:
        '200':
          description: Plugin
          content:
            'application/json':
              schema:
                '$ref': '#/components/schemas/PluginResponse'
    put:
      tags:
      - Plugins
      summary: Update a single plugin
      description: Currently an experimental feature activated using the `--experimental-plugins-api` flag.
      parameters:
      - name: pluginName
        in: path
        required: true
        description: plugin name
        schema:
          type: string
      responses:
        '200':
          description: Plugin
          content:
            'application/json':
              schema:
                '$ref': '#/components/schemas/Plugin'
      requestBody:
        content:
          application/json:
            schema:
              '$ref': '#/components/schemas/PluginUpdateRequest'

  /policies:
    get:
      tags:
        - Policies
      summary: Return list of policies enabled in "policies" section
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
  '/policies/{name}':
    put:
      tags:
        - Policies
      summary: Enable policy
      responses:
        '204':
          description: No Content
    delete:
      tags:
        - Policies
      summary: Disable policy
      responses:
        '204':
          description: No Content
  /api-endpoints:
    get:
      tags:
        - API Endpoints
      summary: Return all API Endpoints
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEndpoints'
  '/api-endpoints/{name}':
    put:
      tags:
        - API Endpoints
      summary: Add API Endpoint
      responses:
        '201':
          description: No Content
        '204':
          description: No Content
    get:
      tags:
        - API Endpoints
      summary: GET API Endpoint
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEndpoint'
    delete:
      tags:
        - API Endpoints
      summary: Remove API Endpoint
      responses:
        '204':
          description: No Content
  /service-endpoints:
    get:
      tags:
        - Service Endpoints
      summary: Return all Service Endpoints
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceEndpoints'
  '/service-endpoints/{name}':
    put:
      tags:
        - Service Endpoints
      summary: Add Service Endpoint
      responses:
        '201':
          description: No Content
        '204':
          description: No Content
    get:
      tags:
        - Service Endpoints
      summary: GET Service Endpoint
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceEndpoint'
    delete:
      tags:
        - Service Endpoints
      summary: remove Service Endpoint
      responses:
        '204':
          description: No Content
  /pipelines:
    get:
      tags:
        - Pipelines
      summary: Return all Pipelines
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pipelines'
  '/pipelines/{name}':
    put:
      tags:
        - Pipelines
      summary: Add Pipeline
      responses:
        '201':
          description: No Content
        '204':
          description: No Content
    get:
      tags:
        - Pipelines
      summary: GET Pipeline
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pipeline'
    delete:
      tags:
        - Pipelines
      summary: Remove Pipeline
      responses:
        '204':
          description: No Content
components:
  schemas:
    APIEndpoint:
      properties:
        host:
          type: string
        paths:
          type: array
          items:
            type: string
    APIEndpoints:
      properties:
        endpointName1:
          $ref: '#/components/schemas/APIEndpoint'
        endpointName2:
          $ref: '#/components/schemas/APIEndpoint'
    ServiceEndpoint:
      properties:
        url:
          type: string
    ServiceEndpoints:
      properties:
        endpointName1:
          $ref: '#/components/schemas/ServiceEndpoint'
        endpointName2:
          $ref: '#/components/schemas/ServiceEndpoint'
    ConditionActionPair:
      properties:
        condition:
          type: object
          properties:
            name:
              type: string
            conditionParam1:
              type: string
        action:
          type: object
          properties:
            actionParam1:
              type: string
            actionParam2:
              type: string
    PipelinePolicy:
      properties:
        policyName:
          type: array
          items:
            $ref: '#/components/schemas/ConditionActionPair'
    Pipeline:
      properties:
        pipelineName:
          type: object
          properties:
            apiEndpoints:
              type: array
              items:
                type: string
            policies:
              type: array
              items:
                $ref: '#/components/schemas/PipelinePolicy'
    Pipelines:
      properties:
        pipelineName1:
          $ref: '#/components/schemas/Pipeline'
        pipelineName2:
          $ref: '#/components/schemas/Pipeline'
    CreateUserRequest:
      required:
      - username
      - firstname
      - lastname
      properties:
        username:
          type: string
          description: Unique identifier of user entity
          example: steve
        email:
          type: string
          description: email of user, configurable, not required by default
          example: steve@example.com
        firstname:
          type: string
          example: Steve
          description: First name of user (custom property configured in User model,
            required by default)
        lastname:
          type: string
          example: Brown
          description: Last name of user (custom property configured in User model,
            required by default
        redirectUri:
          type: string
          description: Oauth2 specific property, not required by default
          example: http://example.com
      type: object
    UpdateUserRequest:
      required:
      - firstname
      - lastname
      properties:
        email:
          type: string
          description: email of user, configurable, not required by default
          example: steve@example.com
        firstname:
          type: string
          example: Steve
          description: First name of user (custom property configured in User model,
            required by default)
        lastname:
          type: string
          example: Brown
          description: Last name of user (custom property configured in User model,
            required by default
        redirectUri:
          type: string
          description: Oauth2 specific property, not required by default
          example: http://example.com
      type: object
    CreateAppRequest:
      required:
      - name
      - userId
      properties:
        userId:
          type: string
          description: username or user Id of owner
          example: steve
        name:
          type: string
          description: title of the app, this is just a text with NO reference to
            applicationId (property id)
          example: my-app
        redirectUri:
          type: string
          description: Oauth2 specific property, not required by default
          example: http://example.com
      type: object
    UpdateAppRequest:
      required:
      - name
      properties:
        name:
          type: string
          description: title of the app, this is just a text with NO reference to
            applicationId (property id)
          example: my-app
        redirectUri:
          type: string
          description: Oauth2 specific property, not required by default
          example: http://example.com
      type: object
    CreateCredentialRequest:
      required:
      - credential
      - consumerId
      - type
      properties:
        credential:
          type: object
          description: custom properties to include in credential, optional
          properties:
            scopes:
              type: array
              items:
                type: string
        consumerId:
          type: string
        type:
          type: string
          enum:
          - basic-auth
          - key-auth
          - oauth2
      type: object
    Scope:
      description: scope
      type: string
      example: admin
    Scopes:
      description: scopes
      type: object
      properties:
        scopes:
          type: array
          items:
            '$ref': '#/components/schemas/Scope'
    User:
      description: Main item in the system. Typically would be used to represent a
        person in Express Gateway. User can have multiple Applications (Apps) and
        Credentials
      properties:
        username:
          type: string
          description: Unique identifier of user entity, 1-to-1 relation with id,
            both can be used to build references to other objects like apps\credentials
            etc.
          example: steve
        id:
          type: string
          description: Autogenerated Unique identifier of user entity, duplicates
            functionality of username
          example: 47bc9fa2-f245-4b47-9cb4-29b8ccb49728
        email:
          type: string
          description: email of user, configurable, not required by default
          example: steve@example.com
        firstname:
          type: string
          example: Steve
          description: First name of user (custom property configured in User model,
            required by default)
        lastname:
          type: string
          example: Brown
          description: Last name of user (custom property configured in User model,
            required by default)
        isActive:
          type: boolean
          description: Flag showing if user will be able to login
          example: true
        redirectUri:
          type: string
          description: Oauth2 specific property, not required by default
          example: http://example.com
        createdAt:
          type: string
          description: Date and time of User creation, RFC-1123 formatted date stamp
          example: Sun Jul 16 2017 00:06:17 GMT+0300 (EEST)
        updatedAt:
          type: string
          description: Date and time of User creation, RFC-1123 formatted date stamp
          example: Sun Jul 16 2017 00:06:17 GMT+0300 (EEST)
      type: object
    App:
      description: This entity is designed to represent non human consumers of API
        endpoints, such as mobile application
      properties:
        name:
          description: application name
          example: my-app
          type: string
        id:
          type: string
          description: Autogenerated Unique identifier of an App
          example: 0e13a310-0319-4780-bf66-d10788e08d8a
        userId:
          type: string
          description: Username or UserId that owns the app
          example: 47bc9fa2-f245-4b47-9cb4-29b8ccb49728
        isActive:
          type: boolean
          description: Flag showing if user will be able to login
          example: true
        redirectUri:
          type: string
          description: Oauth2 specific property, not required by default
          example: http://example.com
        createdAt:
          type: string
          description: Date and time of User creation, RFC-1123 formatted date stamp
          example: Tue Jul 18 2017 17:04:06 GMT+0300 (EEST)
        updatedAt:
          type: string
          description: Date and time of User creation, RFC-1123 formatted date stamp
          example: Tue Jul 18 2017 17:04:06 GMT+0300 (EEST)
      type: object
    Credential:
      description: A container for secret authentication\authorization data
      properties:
        keyId:
          type: string
          description: Only for key-auth, first part of API key
          example: 55tEGsilJkhKoWMS3kkipH
        keySecret:
          type: string
          description: Only for key-auth, second part of API key
          example: 5BNegGCfqW4rhqqCz3A3sM
        consumerId:
          type: string
          description: Username or UserId or AppId that owns the credential
          example: 47bc9fa2-f245-4b47-9cb4-29b8ccb49728
        password:
          type: string
          description: Only for basic-auth, and onfy if autogenerated
          example: 47bc9fa2-f245-4b47-9cb4-29b8ccb49728
        secret:
          type: string
          description: Only for oauth2, and onfy if autogenerated
          example: 47bc9fa2-f245-4b47-9cb4-29b8ccb49728
        type:
          type: string
          enum:
          - basic-auth
          - key-auth
          - oauth2
        isActive:
          type: boolean
          description: Flag showing if user will be able to login
          example: true
        createdAt:
          type: string
          description: Date and time of User creation, RFC-1123 formatted date stamp
          example: Tue Jul 18 2017 17:04:06 GMT+0300 (EEST)
        updatedAt:
          type: string
          description: Date and time of User creation, RFC-1123 formatted date stamp
          example: Tue Jul 18 2017 17:04:06 GMT+0300 (EEST)
      type: object
    Users:
      properties:
        users:
          description: Array of Users
          type: array
          items:
            '$ref': '#/components/schemas/User'
        nextKey:
          type: integer
          description: Reserved for future needs, Always 0
      type: object
    Apps:
      properties:
        users:
          description: Array of Apps
          type: array
          items:
            '$ref': '#/components/schemas/App'
        nextKey:
          type: integer
          description: Reserved for future needs, Always 0
      type: object
    Credentials:
      properties:
        credentials:
          description: Array of Credentials
          type: array
          items:
            '$ref': '#/components/schemas/Credential'
        nextKey:
          type: integer
          description: Reserved for future needs, Always 0
      type: object
    Plugins:
      properties:
        plugins:
          description: Array of Plugins
          type: array
          items:
            '$ref': '#/components/schemas/PluginResponse'
        nextKey:
          type: integer
          description: Reserved for future needs, Always 0
      type: object
    Plugin:
      required:
      - name
      properties:
        name:
          type: string
        description:
          type: string
        package:
          type: string
        version:
          type: string
        disabled:
          type: boolean
          default: false
        state:
          type: string
          enum:
            - awaiting-configuration
            - configured
          default: configured
        options:
          type: array
          items:
            '$ref': '#/components/schemas/PluginOption'
      type: object
    PluginOption:
      properties:
        name:
          type: string
        schema:
          type: object
        value:
            oneOf:
              - type: string
              - type: boolean
              - type: object
              - type: integer
              - type: number
      type: object
    PluginUpdateRequest:
      allOf:
        - '$ref': '#/components/schemas/Plugin'
        - properties:
            addPoliciesToGatewayConfig:
              type: boolean
              default: true
    PluginResponse:
      allOf:
        - '$ref': '#/components/schemas/Plugin'
        - example:
            name: custom-plugin
            description: An example plugin
            package: express-gateway-plugin-custom
            version: 1.1.0
            disabled: false
            state: configured
            options:
            - name: debug
              schema:
                type: string
                title: Debug
                description: Enable debugging
              value: true
    PluginInstallResponse:
      allOf:
        - '$ref': '#/components/schemas/Plugin'
        - example:
            name: custom-plugin
            description: An example plugin
            package: express-gateway-plugin-custom
            version: 1.1.0
            disabled: true
            state: 'awaiting-configuration'
            options:
            - name: debug
              schema:
                type: string
                title: Debug
                description: Enable debugging
  responses:
    StatusUpdateResponse:
      description: Entity status state
      content:
        'application/json':
          schema:
            type: object
            properties:
              status:
                type: string
                description: new state of the Entity
                example: Active
    NotFound:
      description: Entity not found.
    ValidationError:
      description: Supplied entity cannot be processed
    EntityExists:
      description: Conflict due to another resource already exists
  requestBodies:
    Status:
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                description: status
                type: boolean
      description: status