DEV Community: Nana Tech

OpenAPI 3.1, Prisma Schema, and Mermaid Diagrams: All from One AI Prompt

Nana Tech — Fri, 24 Apr 2026 05:59:15 +0000

When you start a new backend project, you need several things to be true simultaneously: the API contract needs to match the database schema, the database schema needs to match the data model in your head, and your diagrams need to reflect all of the above. In practice, these three artifacts drift apart almost immediately — because they're authored in different tools, at different times, by different people.

8sprint takes a different approach: generate all three from a single plain-English description, using specialized AI agents that coordinate with each other to ensure the outputs are consistent by construction.

Here's what that looks like for a real project.

The Prompt

Suppose you're building a multi-tenant SaaS platform for managing marketing campaigns. You describe it like this:

"Multi-tenant marketing campaign platform. Organizations have members with roles (owner, admin, editor, viewer). Organizations run campaigns with start/end dates, budget, and status. Campaigns contain ad groups, which contain individual ads with creative content, targeting parameters, and performance metrics. Need audit logging on all state changes."

That's 57 words. Here's what 8sprint generates from it.

The OpenAPI 3.1 Spec

8sprint produces a complete API contract covering authentication, CRUD operations, tenant isolation, and role checks. Here's a representative excerpt:

openapi: 3.1.0
info:
  title: Campaign Management API
  version: 1.0.0

components:
  schemas:
    Campaign:
      type: object
      required: [id, organizationId, name, status, startDate]
      properties:
        id:
          type: string
          format: uuid
        organizationId:
          type: string
          format: uuid
        name:
          type: string
          maxLength: 255
        status:
          type: string
          enum: [draft, scheduled, active, paused, completed, archived]
        startDate:
          type: string
          format: date
        endDate:
          type: [string, "null"]
          format: date
        budget:
          type: [number, "null"]
          minimum: 0
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    AuditLog:
      type: object
      properties:
        id:
          type: string
          format: uuid
        entityType:
          type: string
          enum: [campaign, ad_group, ad]
        entityId:
          type: string
          format: uuid
        action:
          type: string
          enum: [created, updated, status_changed, deleted]
        actorId:
          type: string
          format: uuid
        changes:
          type: object
          additionalProperties: true
        createdAt:
          type: string
          format: date-time

paths:
  /campaigns:
    get:
      operationId: listCampaigns
      summary: List campaigns for the authenticated organization
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [draft, scheduled, active, paused, completed, archived]
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Paginated campaign list

A few things worth noting in this spec:

Nullable fields use type: [X, "null"] — the OpenAPI 3.1 way to express nullable values, using JSON Schema's type union syntax instead of the nullable: true keyword from OpenAPI 3.0
Standard number formats — OpenAPI defines float and double as standard formats; decimal is not in the specification
AuditLog uses polymorphic entityType/entityId — covers campaigns, ad groups, and ads in a single table without per-entity foreign keys, keeping the design clean and extensible

The spec includes security definitions for JWT bearer auth, tenant-scoped filtering on all list endpoints, and proper response schemas for validation errors — not just the happy path.

The Prisma Schema

Simultaneously, 8sprint generates a Prisma schema that maps directly to the OpenAPI data model:

model Organization {
  id        String   @id @default(uuid())
  name      String
  slug      String   @unique
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  members   OrganizationMember[]
  campaigns Campaign[]
}

model OrganizationMember {
  id             String   @id @default(uuid())
  organizationId String
  userId         String
  role           MemberRole
  createdAt      DateTime @default(now())

  organization Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade)

  @@unique([organizationId, userId])
  @@index([userId])
}

enum MemberRole {
  owner
  admin
  editor
  viewer
}

model Campaign {
  id             String         @id @default(uuid())
  organizationId String
  name           String
  status         CampaignStatus @default(draft)
  startDate      DateTime
  endDate        DateTime?
  budget         Decimal?
  createdAt      DateTime       @default(now())
  updatedAt      DateTime       @updatedAt

  organization Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade)
  adGroups     AdGroup[]
  auditLogs    AuditLog[]

  @@index([organizationId, status])
  @@index([organizationId, startDate])
}

enum CampaignStatus {
  draft
  scheduled
  active
  paused
  completed
  archived
}

model AuditLog {
  id         String   @id @default(uuid())
  entityType String
  entityId   String
  action     String
  actorId    String
  changes    Json     @default("{}")
  createdAt  DateTime @default(now())

  @@index([entityType, entityId])
  @@index([actorId])
}

Notice the alignment: the CampaignStatus enum in Prisma matches the OpenAPI enum exactly. The AuditLog model uses a clean polymorphic design — entityType and entityId are sufficient to reference any entity type (campaign, ad group, or ad) without needing per-entity foreign keys. The indexes on organizationId, status and organizationId, startDate support the filtering and sorting patterns the API spec defines.

This isn't coincidence. The agents that generate the OpenAPI spec and the Prisma schema coordinate through a shared internal representation of your data model, so the outputs stay in sync.

The Mermaid Diagrams

8sprint also produces Mermaid diagrams for your README and architecture documentation. The ER diagram for this project:

erDiagram
    Organization {
        uuid id PK
        string name
        string slug
        datetime createdAt
    }
    OrganizationMember {
        uuid id PK
        uuid organizationId FK
        uuid userId FK
        enum role
    }
    Campaign {
        uuid id PK
        uuid organizationId FK
        string name
        enum status
        date startDate
        date endDate
        decimal budget
    }
    AdGroup {
        uuid id PK
        uuid campaignId FK
        string name
        boolean active
    }
    Ad {
        uuid id PK
        uuid adGroupId FK
        string creativeUrl
        json targetingParams
        json performanceMetrics
    }
    AuditLog {
        uuid id PK
        string entityType
        uuid entityId
        string action
        uuid actorId
        json changes
    }

    Organization ||--o{ OrganizationMember : "has"
    Organization ||--o{ Campaign : "runs"
    Campaign ||--o{ AdGroup : "contains"
    AdGroup ||--o{ Ad : "contains"

This renders directly in GitHub READMEs and any tool that supports Mermaid — Notion, Confluence, GitLab, and most modern documentation platforms.

Beyond the ER diagram, 8sprint generates sequence diagrams for key flows. Here's the campaign status transition flow:

sequenceDiagram
    actor Client
    participant API
    participant DB
    participant AuditService

    Client->>API: PATCH /campaigns/{id} {status: "active"}
    API->>API: Validate role (admin+)
    API->>DB: Check campaign exists and belongs to org
    DB-->>API: Campaign record
    API->>DB: UPDATE campaign SET status = 'active'
    DB-->>API: Updated campaign
    API->>AuditService: Log(entityType: campaign, action: status_changed)
    AuditService->>DB: INSERT audit_log
    API-->>Client: 200 OK {campaign}

The Full Package

Beyond these three core artifacts, 8sprint also generates:

README.md — project overview, setup instructions, environment variables
API Guide — authentication flow, pagination conventions, error format
Data Dictionary — definitions for every field in the schema
Error Catalog — all error codes and their meanings
Deployment Checklist — environment setup, database migration steps

All of this from one prompt, in under 3 minutes.

Why Synchronized Outputs Matter

The real value isn't the individual artifacts — it's that they start synchronized. When an OpenAPI spec and a Prisma schema are written by different people at different times, mismatches are inevitable: a field that's required in the spec is nullable in the database, an enum value that exists in the schema doesn't appear in the API response, a foreign key that should cascade doesn't.

Starting from a single generated source means these inconsistencies are caught before a line of application code is written. You still need to review the outputs — the AI can misinterpret requirements, and you know your project better than any model does. But the baseline is coherent, and reviewing a coherent baseline is much faster than reconciling three independently authored documents.

Try 8sprint on Your Next Project

Free tier: 3 generations per month. No credit card required. Pro ($39/mo) for unlimited generations. Team ($99/mo) for collaborative workspaces.

Generate your architecture package at 8sprint.com →

Describe your project in plain English. Get OpenAPI 3.1, Prisma schema, Mermaid diagrams, and 15+ docs in under 3 minutes.

8sprint is an AI documentation platform in open beta. Feedback from real projects directly shapes development priorities.

Why Your API Documentation Is Always Out of Date (and How to Fix It)

Nana Tech — Fri, 24 Apr 2026 05:53:30 +0000

Here's a scenario that plays out on engineering teams every day.

A developer is onboarding to a new project. They find the API docs and start building. Two days later, they open a pull request and get a comment: "That endpoint was deprecated three months ago. We use /v2/users/me now." The docs weren't wrong when they were written. They just weren't maintained.

This isn't a process failure. It's a structural one. Documentation written after code exists in a different place, in a different format, maintained by different people, with different incentives. Of course it drifts.

The Root Cause: Documentation Is Treated as a Deliverable, Not a Constraint

Most teams think of documentation as something you write at the end of a feature — after the code is merged, after QA is done, when someone has a moment. That sequencing guarantees the docs will lag reality.

The alternative isn't to demand developers write better docs in their free time. It's to make documentation a first-class artifact that precedes implementation — not a postscript to it.

The tool that enables this for APIs is the OpenAPI Specification. An OpenAPI spec is machine-readable, version-controllable, and the single source of truth for your API contract. When it lives in your repo alongside your code, it gets reviewed in pull requests. Linters flag when implementation diverges from spec. Mock servers let frontend teams build against the spec before the backend ships.

But here's the problem: writing OpenAPI specs by hand is tedious enough that most teams skip it — or write a minimal version and never expand it.

Why OpenAPI Specs Stay Incomplete

OpenAPI 3.1 is comprehensive. That's part of the problem. A production-quality spec needs:

Complete schema definitions with proper types, formats, and constraints
All response variants: success, validation errors, auth errors, rate limits
Security scheme definitions
Parameter documentation for query, path, and header values
Pagination patterns
Clear operationId naming for code generation

Writing this for a moderately complex API with 20+ endpoints can take a full day. And that day isn't available at the start of a project, when architecture decisions are still being made. So teams write a skeleton spec, or use something like Swagger annotations inline in code (which creates coupling and is equally hard to keep current), or skip it entirely.

The Spec Generator Approach

A newer approach uses AI to generate an OpenAPI spec directly from a plain-English description of what an API should do. Instead of translating requirements → code → annotations → spec, you go directly from requirements → spec → code.

Here's what that looks like in practice with 8sprint:

You describe your API in a paragraph or two:

"I need an e-commerce API with products, categories, orders, and customers. Products belong to categories. Orders have line items and status tracking (pending, confirmed, shipped, delivered, cancelled). Customers have addresses. I need filtering and sorting on the product list, and authentication for the order and customer endpoints."

8sprint routes this through specialized AI agents and produces a complete OpenAPI 3.1 spec in under 3 minutes. Here's part of the orders section:

paths:
  /orders:
    post:
      operationId: createOrder
      summary: Create a new order
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [customerId, lineItems]
              properties:
                customerId:
                  type: string
                  format: uuid
                lineItems:
                  type: array
                  minItems: 1
                  items:
                    type: object
                    required: [productId, quantity]
                    properties:
                      productId:
                        type: string
                        format: uuid
                      quantity:
                        type: integer
                        minimum: 1
      responses:
        '201':
          description: Order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized
        '422':
          description: Business rule violation (e.g., product out of stock)

This level of detail — validation rules, multiple response codes, proper schema references — takes experience and discipline to write manually. The AI generates it as a baseline you can review and adjust.

How This Fixes the Documentation Drift Problem

When you start with a generated spec and treat it as the source of truth:

Implementation follows the spec, not the other way around. Backend developers implement what the spec defines. Frontend developers mock against it. Both sides know what to expect.

The spec lives in version control. Changes to the API require changes to the spec — reviewed in pull requests like any other code change.

Tooling enforces the contract. Libraries like openapi-enforcer, dredd, or Prism can run contract tests in CI, failing a build if the implementation diverges from the spec.

Onboarding uses accurate documentation. Because the spec was accurate at implementation time and maintained through review, new developers start with a reliable reference.

The Practical Starting Point

You don't need to overhaul your entire development process to benefit from this. The practical starting point:

Use a tool like 8sprint to generate a spec from your project description
Review it for correctness — adjust any details the AI misunderstood
Commit it to your repository as the starting point for implementation
Add a linter (like redocly lint or spectral) to your CI pipeline to catch spec regressions

The spec won't stay perfect automatically. But it starts from a better position than "we'll document this later," and review tooling makes drift visible instead of invisible.

Start with a Spec, Not a Wish

Documentation isn't out of date because developers are lazy or disorganized. It's out of date because it's written after the fact, in a format that's separate from the code, with no automated enforcement keeping it honest.

Starting with an OpenAPI spec — generated from your requirements before you write a line of implementation — inverts the problem. Documentation becomes a constraint that the implementation must satisfy, not a record of what the implementation happened to do.

Generate your OpenAPI spec from a description at 8sprint.com →

Free tier: 3 generations/month. No credit card required.

8sprint is an AI documentation platform that generates OpenAPI 3.1 specs, Prisma schemas, architecture diagrams, and 15+ supporting docs from a plain-English project description.

From Idea to OpenAPI Spec in 3 Minutes with 8sprint

Nana Tech — Fri, 24 Apr 2026 05:53:20 +0000

You have an idea for an API. Maybe it's a SaaS backend, a microservice, or an internal tool. The idea is clear in your head, but turning it into a proper OpenAPI spec — the kind that actually ships with your project — takes hours. You have to think through every endpoint, every request body, every response schema, every status code.

What if you could skip that grunt work?

8sprint is an AI documentation platform that takes your project idea and produces a complete, production-ready architecture package — including an OpenAPI 3.1 spec, Prisma schema, Mermaid diagrams, and over 15 markdown docs — in under 3 minutes.

Here's how it works.

Step 1: Describe Your Project in Plain English

Start at 8sprint.com and describe your project. You don't need formal language, bullet points, or an outline. Just write what you'd tell a senior engineer in a 5-minute Slack message.

Here's an example prompt:

"Build a project management API with users, teams, projects, and tasks. Users can belong to multiple teams. Teams own projects. Projects contain tasks with status (todo, in_progress, done), due dates, and assignees. I need JWT auth, pagination on list endpoints, and role-based access for team admins vs members."

That's it. Hit generate.

Step 2: 8 Specialized AI Agents Get to Work

8sprint routes your description through 8 specialized agents — each responsible for a different piece of your architecture:

Requirements Extractor — parses your description and builds a structured model of resources, relationships, and constraints
Tech Stack Validator — identifies your target stack and validates compatibility of the proposed architecture
Architecture Designer — maps out resource relationships, endpoint surface, and system boundaries
Schema & API Generator — writes the full OpenAPI 3.1 spec with schemas, paths, and security definitions, and produces the Prisma schema
Documentation Writer — generates README, API guide, data dictionary, and 12+ supporting docs
Quality Assurance — validates consistency and correctness across all outputs
GitHub Repository Creator — packages all artifacts and pushes them to a new GitHub repository
UX/UI Design Advisor — identifies frontend considerations and surface-area recommendations

Step 3: Review Your Generated OpenAPI Spec

Within 3 minutes, 8sprint delivers a complete OpenAPI 3.1 spec. Here's a condensed excerpt from the project management example above:

openapi: 3.1.0
info:
  title: Project Management API
  version: 1.0.0
  description: Team-based project and task management with role-based access control

servers:
  - url: https://api.yourapp.com/v1

security:
  - bearerAuth: []

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    Task:
      type: object
      required: [id, title, status, projectId]
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
          maxLength: 255
        status:
          type: string
          enum: [todo, in_progress, done]
        dueDate:
          type: [string, "null"]
          format: date-time
        assigneeId:
          type: [string, "null"]
          format: uuid
        projectId:
          type: string
          format: uuid
        createdAt:
          type: string
          format: date-time

paths:
  /tasks:
    get:
      summary: List tasks
      parameters:
        - name: projectId
          in: query
          required: true
          schema:
            type: string
            format: uuid
        - name: status
          in: query
          schema:
            type: string
            enum: [todo, in_progress, done]
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Paginated task list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Task'
                  meta:
                    type: object
                    properties:
                      total:
                        type: integer
                      page:
                        type: integer
                      limit:
                        type: integer

This is valid OpenAPI 3.1 — note the type: [string, "null"] union syntax for nullable fields, which replaced the nullable: true keyword from OpenAPI 3.0. You can load this straight into Swagger UI, Redoc, or Stoplight — or feed it directly into code generators.

Step 4: Get the Full Architecture Package

The OpenAPI spec is just one artifact. 8sprint also delivers:

Prisma schema — with correct @relation annotations, cascade rules, and indexed foreign keys
Mermaid ER diagram — showing entity relationships for your README
Mermaid sequence diagrams — for key flows like auth, task creation, and role checks
15+ markdown docs — including a data dictionary, API guide, environment variables reference, error catalog, and deployment checklist

Step 5: Push to GitHub in One Click

The GitHub Repository Creator agent packages all artifacts — spec, schema, diagrams, and docs — and pushes them to a new GitHub repository. Your project starts with documentation already in place, not as an afterthought.

Why This Matters for AI API Documentation

The traditional workflow looks like this: build → document → realize the docs are already stale → abandon. The 8sprint workflow flips it: describe → document → build.

Starting with a solid OpenAPI spec means your team can:

Generate mock servers immediately with tools like Prism
Start frontend or client development before the backend is built
Run contract tests from day one
Onboard new engineers with accurate, structured reference material

Try It Free

8sprint's free tier lets you run 3 generations per month at no cost — enough to validate the workflow on a real project. Pro ($39/mo) gives you unlimited generations and priority processing. Team ($99/mo) adds collaboration features.

Generate your OpenAPI spec now at 8sprint.com →

No credit card required. No YAML expertise needed. Just describe what you're building.

8sprint is an AI documentation platform in open beta. The tool is actively developed — feedback from real projects shapes the roadmap.