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 which is configured in compliance with the original specification (OpenAPI/ Swagger or Postman respectively).

👍

Note

IBM API Connect Support now accessible to users, allows for seamless integration with Swagger 2.0 and OpenAPI 3.0 (already supported). With this update, creating scans using the IBM API Connect specification directly exported from API Connect is a breeze, eliminating the need for additional schema conversion.

IBM API Connect Support now accessible to users, allows for seamless integration with Swagger 2.0 and OpenAPI 3.0 (already supported). With this update, creating scans using the IBM API Connect specification directly exported from API Connect is a breeze, eliminating the need for additional schema conversion.

Bright validates the API schemas you upload for a new scan, either via the 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), then 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.
1564
  • 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”.
1559

If an API schema is not ready for scanning, then you should first correct it according to the specifications using the Schema Editor. 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. You can find the detailed information about configuration requirements and error types 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"
     }
  ]
}