Create a specification

Created:

May 11, 2023

Updated:

September 18, 2024



Specifications can be used to group information for an API. Create specifications on the FireTail platform to easily view inventory data for that API. To create a specification, upload a JSON or YAML file into the platform.

1. Navigate to APIs in the FireTail platform.

2. Select the API you want to create the specification for.

3. Click the Specifications tab.

4. Click Upload/Generate Specification.

Select the Upload Specification option.

5. Enter a name for the specification.

6. Click Select File. Navigate to where you have your .json or .yml file saved and select that file.

7. Click Submit.

If you have successfully uploaded the specification, you are taken directly to the specifications page. If there is an error on the file, for example, if it is formatted incorrectly or missing required information then an error message is displayed indicating what the problem is.

JSON file example


{
 "openapi": "3.0.3",
 "info": {
   "title": "OpenAPI 3.0",
   "description": "This is a sample OpenAPI 3.0 specification.",
   "version": "1.0.0"
 },
 "tags": [
   {
     "name": "user",
     "description": "Operations about user"
   }
 ],
 "paths": {
   "/user": {
     "post": {
       "tags": [
         "user"
       ],
       "summary": "Create user",
       "description": "This can only be done by the logged in user.",
       "operationId": "createUser",
       "requestBody": {
         "description": "Created user object",
         "content": {
           "application/json": {
             "schema": {
               "$ref": "#/components/schemas/User"
             }
           },
           "application/xml": {
             "schema": {
               "$ref": "#/components/schemas/User"
             }
           },
           "application/x-www-form-urlencoded": {
             "schema": {
               "$ref": "#/components/schemas/User"
             }
           }
         }
       },
       "responses": {
         "default": {
           "description": "successful operation",
           "content": {
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/User"
               }
             },
             "application/xml": {
               "schema": {
                 "$ref": "#/components/schemas/User"
               }
             }
           }
         }
       }
     }
   },
      "delete": {
       "tags": [
         "user"
       ],
       "summary": "Delete user",
       "description": "This can only be done by the logged in user.",
       "operationId": "deleteUser",
       "parameters": [
         {
           "name": "username",
           "in": "path",
           "description": "The name that needs to be deleted",
           "required": true,
           "schema": {
             "type": "string"
           }
         }
       ],
       "responses": {
         "400": {
           "description": "Invalid username supplied"
         },
         "404": {
           "description": "User not found"
         }
       }
     }
   }
 },
 "components": {
   "schemas": {
     "User": {
       "type": "object",
       "properties": {
         "id": {
           "type": "integer",
           "format": "int64",
           "example": 10
         },
         "username": {
           "type": "string",
           "example": "theUser"
         },
         "firstName": {
           "type": "string",
           "example": "John"
         },
         "lastName": {
           "type": "string",
           "example": "James"
         },
         "email": {
           "type": "string",
           "example": "john@email.com"
         },
         "password": {
           "type": "string",
           "example": "12345"
         },
         "phone": {
           "type": "string",
           "example": "12345"
         },
         "userStatus": {
           "type": "integer",
           "description": "User Status",
           "format": "int32",
           "example": 1
         }
       },
       "xml": {
         "name": "user"
       }
     }
   },
   "requestBodies": {
     "UserArray": {
       "description": "List of user object",
       "content": {
         "application/json": {
           "schema": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/User"
             }
           }
         }
       }
     }
   }

YAML file example


openapi: 3.0.3
info:
 title: OpenAPI 3.0
 description: This is a sample OpenAPI 3.0 specification.
 version: 1.0.0
tags:
 - name: user
   description: Operations about user
paths:
 /user:
   post:
     tags:
       - user
     summary: Create user
     description: This can only be done by the logged in user.
     operationId: createUser
     requestBody:
       description: Created user object
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/User'
         application/xml:
           schema:
             $ref: '#/components/schemas/User'
         application/x-www-form-urlencoded:
           schema:
             $ref: '#/components/schemas/User'
     responses:
       default:
         description: successful operation
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/User'
           application/xml:
             schema:
               $ref: '#/components/schemas/User'
   put:
     tags:
       - user
     summary: Update user
     description: This can only be done by the logged in user.
     operationId: updateUser
     parameters:
       - name: username
         in: path
         description: name that needs to be deleted
         required: true
         schema:
           type: string
     requestBody:
       description: Update an existent user in the store
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/User'
         application/xml:
           schema:
             $ref: '#/components/schemas/User'
         application/x-www-form-urlencoded:
           schema:
             $ref: '#/components/schemas/User'
     responses:
       default:
         description: successful operation
   delete:
     tags:
       - user
     summary: Delete user
     description: This can only be done by the logged in user.
     operationId: deleteUser
     parameters:
       - name: username
         in: path
         description: The name that needs to be deleted
         required: true
         schema:
           type: string
     responses:
       '400':
         description: Invalid username supplied
       '404':
         description: User not found
components:
 schemas:
   User:
     type: object
     properties:
       id:
         type: integer
         format: int64
         example: 10
       username:
         type: string
         example: theUser
       firstName:
         type: string
         example: John
       lastName:
         type: string
         example: James
       email:
         type: string
         example: john@email.com
       password:
         type: string
         example: '12345'
       phone:
         type: string
         example: '12345'
       userStatus:
         type: integer
         description: User Status
         format: int32
         example: 1
     xml:
       name: user
 requestBodies:
   UserArray:
     description: List of user object
     content:
       application/json:
         schema:
           type: array
           items:
             $ref: '#/components/schemas/User'