API Specification

Here, we cover how to write an OpenAPI specification (aka Swagger specification) file in YAML as well as how to upload the specification file (.yaml file) on Ainize Project Page. The Swagger file enables you to test if Ainized endpoints are correctly working. Furthermore, it also provides how-to instructions to the API users.

Here is a template yaml file for Ainized projects:

openapi: 3.0.0   # Open api version

info:   # Set basic infomation
  title: your-swagger-example
  version: 0.1.1

servers:   # Set your server endpoint
  - url: https://${BRANCH_NAME}-${REPO_NAME}-${GITHUB_USER_NAME}.endpoint.ainize.ai

paths:
  /path/to/get/method:   # GET method path
    get:
      summary: your get method
      description: your get method's description
      parameters:   # Set parameter values here
        - name: param1   # Set parameter name
          in: query   # Select amongst query, header, path, and cookie
          required: true
          allowReserved: true   # Option for percent-encoding, default; false 
          schema:
            type: string
      responses:   # Set response
        '200':
          description: Successful Response
          content:   # Descriptions of potential response payloads (optional)
            application/json:
              schema:   # Set data types
                type: object
                properties:
                  score:
                    type: number
        '400':
          description: Bad Request Error
        '500':
          description: Server-side Error
        '503':
          description: Server is not ready
        default: 
          description: Unexpected Error 

There are several tools for debugging OpenAPI specification:

• Swagger Editor

• Postman

• OpenAPI.tools

How to create and publish a Swagger file.

1. Deploy your Github project

At this point, you can get the server endpoint. Modify swagger.yaml to include this address.

2. Create a Swagger file (swagger.yaml file)

3. Go to the API tab in your Ainized project's page

4. Upload a Swagger file

5. Now you can click Try it out and Execute