Configuring an API Schema

To scan API endpoints, you need to upload an API schema file to Bright. For a scan to be successful, please make sure that you are using a valid schema that is configured in compliance with the original specification (OpenAPI/ Swagger or Postman, respectively).

Bright validates the API schemas you upload for a new scan via Bright storage or directly during the scan setup. If the schema is configured incorrectly (breaks the specification rules), the Bright Schema Editor (Linter) will mark the file as “not ready for scanning”, display an error message and prevent the user from running a scan.

You can easily detect invalid files which cannot be used for a scan by the following indicators:

If an uploaded file contains an error (for example, a host/server is not specified in the schema, or some parameters are specified incorrectly), it will be indicated as NOT ready for scanning in the relevant column of the Bright storage.

The API schemas that are not ready for scanning are also marked with a warning icon (meaning that fixes are required) when selecting a pre-uploaded file during the scan setup.

If a file that requires fixes is selected during the scan setup, the following warning message appears below API settings: “The selected specification file cannot be used to start a scan. Please use the Schema Editor to fix the issues”.

If an API schema is not ready for scanning, you should correct it according to the Schema Editor's specifications. See Edit an Uploaded API Schema for more information.

The Start scan button will be disabled until you fix all the errors in the schema. Detailed information about configuration requirements and error types is in the Troubleshooting section.

The examples of API schemas that can be properly defined and accepted for scanning by Bright are given below.

Example 1: Swagger.json

{
 "swagger": "2.0",
 "info": {
   "title": "schema",
   "description": "My API Schema",
   "version": "0.4.5"
 },
 "host": "brokencrystals.com",
 "basePath": "/home",
 "schemes": [
   "https"
 ],
 "paths": {
   "/user/{userEmail}": {
     "get": {
       "parameters": [
         {
           "in": "path",
           "name": "userEmail",
           "required": true,
           "type": "string",
           "default": "[email protected]"
         }
       ],
       "produces": [
         "application/json"
       ],
       "responses": {
         "200": {
           "description": "OK"
         }
       }
     }
   }
 }
}

Example 2: Swagger.yaml

swagger: "2.0"
info:
 title: schema
 description: My API Schema
 version: 0.4.5
host: brokencrystals.com
basePath: /home
schemes:
 - https
paths:
 /user/{userEmail}:
   get:
     parameters:
     - in: path
       name: userEmail
       required: true
       type: "string"
       default: "[email protected]"
     produces:
       - application/json
     responses:
       200:
         description: OK

Example 3: OpenAPI.json

{
 "openapi": "3.0.1",
 "info": {
   "title": "schema",
   "description": "My API Schema",
   "version": "0.4.5"
 },
 "servers": [
   {
     "url": "https://brokencrystals.com/{basePath}",
     "variables": {
       "basePath": {
         "default": "/home"
       }
     }
   }
 ],
 "paths": {
   "/user/{userEmail}": {
     "post": {
       "operationId": "userEmail",
       "parameters": [
         {
           "name": "userEmail",
           "in": "path",
           "required": true,
           "schema": {
             "type": "string",
             "default": "[email protected]"
           }
         }
       ],
       "responses": {
         "200": {
           "description": "200 response",
           "content": {
             "application/json": {
               "schema": {
                 "$ref": "#"
               }
             }
           }
         }
       }
     }
   }
 }
}

Example 4: OpenAPI.yaml

openapi: "3.0.1"
info:
 title: "schema"
 description: "My API Schema"
 version: "0.4.5"
servers:
- url: "https://brokencrystals.com/{basePath}"
  variables:
   basePath:
     default: "/home"
paths:
 /user/{userEmail}:
   post:
     operationId: "userEmail"
     parameters:
     - name: "userEmail"
       in: "path"
       required: true
       schema:
         type: "string"
         default: "[email protected]"
     responses:
       "200":
         description: "200 response"
         content:
           application/json:
             schema:
               $ref: "#"

Example 5: Postman

{
  "info": {
     "name": "schema",
     "description": "My API Schema",
     "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
     {
        "name": "/user/:userEmail",
        "request": {
           "method": "GET",
           "header": [],
           "url": {
              "raw": "{{baseUrl}}/user/:userEmail",
              "host": [
                 "{{baseUrl}}"
              ],
              "path": [
                 "user",
                 ":userEmail"
              ],
              "variable": [
                 {
                    "key": "userEmail",
                    "value": "docs@brightsec",
                    "description": "(Required) "
                 }
              ]
           }
        },
        "response": [
           {
              "name": "OK",
              "originalRequest": {
                 "method": "GET",
                 "header": [],
                 "url": {
                    "raw": "{{baseUrl}}/user/:userEmail",
                    "host": [
                       "{{baseUrl}}"
                    ],
                    "path": [
                       "user",
                       ":userEmail"
                    ],
                    "variable": [
                       {
                          "key": "userEmail"
                       }
                    ]
                 }
              },
              "status": "OK",
              "code": 200,
              "header": [
                 {
                    "key": "Content-Type",
                    "value": "text/plain"
                 }
              ],
              "cookie": [],
              "body": ""
           }
        ]
     }
  ],
  "variable": [
     {
        "key": "baseUrl",
        "value": "https://brokencrystals.com/home",
        "type": "string"
     }
  ]
}