Skip to main content

Understanding OpenAPI Specifications

Don't worry - you don't need to become a coding expert to use ValkyrAI! This guide explains OpenAPI specifications in simple terms.

What's an OpenAPI Specification Anyway?​

Think of an OpenAPI specification (or "spec") as a blueprint for your app. It's like a recipe that tells ThorAPI what to build for you.

The spec defines:

  • What objects your app will work with (users, products, orders, etc.)
  • What information those objects contain (name, price, email, etc.)
  • What actions can be performed on those objects (create, view, update, delete)

Why Use Specifications Instead of Just Building?​

Good question! Here's why specs are awesome:

  1. They're human-readable: You can understand what your app does by reading the spec
  2. They're standardized: OpenAPI is an industry standard used by developers worldwide
  3. They're reusable: Once you create a spec, you can generate different versions of your app
  4. They save time: By focusing on the "what" instead of the "how," you skip months of coding

Basic OpenAPI Structure (The Simple Version)​

A basic OpenAPI spec has these main parts:

1. Info Section​

This is just basic information about your API:

openapi: 3.0.0
info:
  title: My Product Catalog
  version: 1.0.0
  description: A simple product catalog API

2. Objects (Called "Schemas")​

These define the things your app works with:

components:
  schemas:
    Product:
      type: object
      properties:
        name:
          type: string
        price:
          type: number

This example defines a Product with a name and price.

3. Paths (The Actions)​

These define what your app can do with those objects:

paths:
  /products:
    get:
      summary: Get all products
    post:
      summary: Create a new product
  /products/{productId}:
    get:
      summary: Get a product by ID
    put:
      summary: Update a product
    delete:
      summary: Delete a product

The Good News: ValkyrAI Makes This Easy!​

Here's how ValkyrAI simplifies working with OpenAPI specs:

  1. Templates: Start with pre-made templates for common apps
  2. Visual Editor: Use our point-and-click interface to define objects
  3. AI Assistance: Ask our AI to help you create or modify your spec
  4. Auto-Generation: Hit the "Generate" button and watch ThorAPI turn your spec into code

Example: A Simple Product Spec​

Here's how you might define a Product in your spec:

components:
  schemas:
    Product:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          description: The product name
        description:
          type: string
        price:
          type: number
          format: float
        category:
          type: string
          enum: [Electronics, Clothing, Food, Books]
        inStock:
          type: boolean
          default: true
      required:
        - name
        - price

This tells ThorAPI that:

  • Each product has an ID, name, description, price, category, and stock status
  • The name and price are required
  • Categories can only be Electronics, Clothing, Food, or Books
  • Products are in stock by default

Relationships Between Objects​

Apps usually have multiple objects that relate to each other. For example, an order might contain products:

Order:
  type: object
  properties:
    id:
      type: string
      format: uuid
    customer:
      $ref: '#/components/schemas/Customer'
    products:
      type: array
      items:
        $ref: '#/components/schemas/Product'
    total:
      type: number

The $ref part tells ThorAPI that an order contains a customer and multiple products defined elsewhere in your spec.

What Happens When You Generate?​

When you hit the "Generate" button:

  1. ThorAPI reads your OpenAPI spec
  2. It creates database tables for each object
  3. It generates API endpoints for all the actions
  4. It creates frontend components for each object
  5. It wires everything together with proper security and validation

Remember: You Don't Have to Be Perfect!​

Your spec doesn't have to be perfect the first time! You can:

  1. Start simple and add more details later
  2. Use templates to get started quickly
  3. Ask ValorIDE to help modify your generated app
  4. Regenerate whenever you update your spec

Next Steps​

Now that you understand the basics of OpenAPI specifications, you're ready to:

Remember: ValkyrAI is here to make app development easy for everyone - not just coding experts!