OpenAPI Format

Learn how to use OpenAPI (Swagger) specifications with moclojer. Import your OpenAPI 3.0/3.1 specs and generate mocks automatically.

Moclojer supports OpenAPI 3.0 and 3.1 (formerly known as Swagger), allowing you to use your existing API specifications to generate mocks automatically. No need to rewrite anything in moclojer YAML!

What Is OpenAPI?

OpenAPI Specification is a standard for describing RESTful APIs in a machine-readable format. It's widely used for:

API documentation
Automatic SDK generation
Contract validation
Mock servers (like moclojer!)

Why Use OpenAPI with Moclojer?

✅ Reusability: Use your existing OpenAPI specs ✅ Standardization: OpenAPI is an industry standard ✅ Zero configuration: Moclojer converts automatically ✅ Validation: OpenAPI specs include validation schemas ✅ Living documentation: Your spec is documentation + mock

OpenAPI Support in Moclojer

Supported Versions

✅ OpenAPI 3.0.x
✅ OpenAPI 3.1.x
⚠️ Swagger 2.0 (partial support - recommend converting to 3.x)

Accepted Formats

✅ JSON (.json)
✅ YAML (.yml, .yaml)

Quick Start

1. Create or Get an OpenAPI Spec

Minimal example (openapi.yml):

openapi: 3.0.0
info:
  title: Users API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List all users
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string
              example:
                - id: 1
                  name: Alice
                - id: 2
                  name: Bob

2. Start Moclojer with OpenAPI

# Using local file
moclojer --config openapi.yml

# Or specify port
moclojer --config openapi.yml --port 3000

# Enable CORS
moclojer --config openapi.yml --enable-cors

3. Test

curl http://localhost:8000/users

Response:

[
  {"id": 1, "name": "Alice"},
  {"id": 2, "name": "Bob"}
]

🎉 Done! Moclojer automatically converted your OpenAPI spec into functional endpoints.

How Moclojer Converts OpenAPI

Automatic Conversion

Moclojer automatically detects it's an OpenAPI spec and converts:

# OpenAPI spec
paths:
  /users/{id}:          # → path: /users/:id
    get:                # → method: GET
      responses:
        '200':          # → status: 200
          content:
            application/json:
              example:  # → body
                id: 1
                name: John

Results in (internal moclojer equivalent):

- endpoint:
    method: GET
    path: /users/:id
    response:
      status: 200
      headers:
        Content-Type: application/json
      body: >
        {
          "id": 1,
          "name": "John"
        }

Path Parameters

OpenAPI uses {param}, moclojer converts to :param:

# OpenAPI
paths:
  /users/{userId}/posts/{postId}:
    get:
      parameters:
        - name: userId
          in: path
          schema:
            type: integer
        - name: postId
          in: path
          schema:
            type: integer

Converted to: /users/:userId/posts/:postId

With types:

type: integer → :userId|int
type: string → :userId|string

Query Parameters

# OpenAPI
paths:
  /products:
    get:
      parameters:
        - name: category
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer

Moclojer understands and accepts:

curl "http://localhost:8000/products?category=electronics&limit=10"

Request Body

# OpenAPI
paths:
  /users:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                email:
                  type: string
            example:
              name: John Doe
              email: [email protected]

Moclojer uses the example for the response.

Complete OpenAPI Examples

Example 1: Simple User API

openapi: 3.0.0
info:
  title: Users API
  description: API for managing users
  version: 1.0.0

servers:
  - url: http://localhost:8000
    description: Local mock server

paths:
  /users:
    get:
      summary: List all users
      operationId: listUsers
      tags:
        - users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  meta:
                    type: object
                    properties:
                      total:
                        type: integer
                      page:
                        type: integer
              example:
                data:
                  - id: 1
                    name: Alice Johnson
                    email: [email protected]
                  - id: 2
                    name: Bob Smith
                    email: [email protected]
                meta:
                  total: 100
                  page: 1

    post:
      summary: Create a new user
      operationId: createUser
      tags:
        - users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserInput'
            example:
              name: Carol Davis
              email: [email protected]
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              example:
                id: 3
                name: Carol Davis
                email: [email protected]
                createdAt: "2024-01-15T10:00:00Z"

  /users/{id}:
    get:
      summary: Get user by ID
      operationId: getUserById
      tags:
        - users
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              example:
                id: 1
                name: Alice Johnson
                email: [email protected]
                createdAt: "2024-01-01T00:00:00Z"
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: "Not Found"
                message: "User with ID 999 not found"

    put:
      summary: Update user
      operationId: updateUser
      tags:
        - users
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserInput'
      responses:
        '200':
          description: User updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

    delete:
      summary: Delete user
      operationId: deleteUser
      tags:
        - users
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: User deleted

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        email:
          type: string
          format: email
        createdAt:
          type: string
          format: date-time

    UserInput:
      type: object
      required:
        - name
        - email
      properties:
        name:
          type: string
          minLength: 1
        email:
          type: string
          format: email

    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string

Test:

# List users
curl http://localhost:8000/users

# With pagination
curl "http://localhost:8000/users?page=1&limit=5"

# Get specific user
curl http://localhost:8000/users/1

# Create user
curl -X POST http://localhost:8000/users \
  -H "Content-Type: application/json" \
  -d '{"name": "New User", "email": "[email protected]"}'

# Update user
curl -X PUT http://localhost:8000/users/1 \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Name", "email": "[email protected]"}'

# Delete user
curl -X DELETE http://localhost:8000/users/1

Example 2: E-commerce API

openapi: 3.0.0
info:
  title: E-commerce API
  version: 1.0.0

paths:
  /products:
    get:
      summary: List products
      parameters:
        - name: category
          in: query
          schema:
            type: string
        - name: minPrice
          in: query
          schema:
            type: number
        - name: maxPrice
          in: query
          schema:
            type: number
      responses:
        '200':
          description: Products list
          content:
            application/json:
              example:
                products:
                  - id: 1
                    name: "Laptop"
                    price: 999.99
                    category: "electronics"
                  - id: 2
                    name: "Mouse"
                    price: 29.99
                    category: "electronics"

  /products/{productId}:
    get:
      summary: Get product details
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Product details
          content:
            application/json:
              example:
                id: 1
                name: "Laptop"
                description: "High-performance laptop"
                price: 999.99
                category: "electronics"
                stock: 50

  /cart:
    post:
      summary: Add to cart
      requestBody:
        content:
          application/json:
            example:
              productId: 1
              quantity: 2
      responses:
        '200':
          description: Added to cart
          content:
            application/json:
              example:
                cartId: "cart-123"
                items:
                  - productId: 1
                    quantity: 2
                    subtotal: 1999.98
                total: 1999.98

  /orders:
    post:
      summary: Create order
      requestBody:
        content:
          application/json:
            example:
              cartId: "cart-123"
              shippingAddress:
                street: "123 Main St"
                city: "New York"
                zipCode: "10001"
      responses:
        '201':
          description: Order created
          content:
            application/json:
              example:
                orderId: "order-456"
                status: "pending"
                total: 1999.98
                createdAt: "2024-01-15T10:00:00Z"

Multiple Responses by Status Code

OpenAPI allows defining multiple responses:

paths:
  /users/{id}:
    get:
      responses:
        '200':
          description: Success
          content:
            application/json:
              example:
                id: 1
                name: "John"
        '404':
          description: Not found
          content:
            application/json:
              example:
                error: "User not found"
        '500':
          description: Server error
          content:
            application/json:
              example:
                error: "Internal server error"

Moclojer uses the first example found (usually 200).

To simulate errors, create specific endpoints:

# In moclojer, add separate endpoints for errors
- endpoint:
    path: /users/999
    response:
      status: 404
      body: '{"error": "User not found"}'

Headers and Content-Type

OpenAPI defines headers automatically:

responses:
  '200':
    description: Success
    headers:
      X-RateLimit-Limit:
        schema:
          type: integer
        example: 100
      X-RateLimit-Remaining:
        schema:
          type: integer
        example: 99
    content:
      application/json:
        example:
          data: []

Moclojer automatically adds:

Content-Type based on content
Custom headers defined in headers

Schemas and $ref

OpenAPI uses $ref to reuse schemas:

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

paths:
  /users/{id}:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              example:
                id: 1
                name: "Alice"

Moclojer resolves $ref and uses the provided example.

Security Schemes (Authentication)

OpenAPI defines security schemes:

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

security:
  - bearerAuth: []

paths:
  /protected:
    get:
      summary: Protected endpoint
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              example:
                message: "You are authenticated!"
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                error: "Unauthorized"

Note: Moclojer does not validate authentication automatically. To simulate:

# Add endpoint for invalid token
- endpoint:
    path: /protected
    response:
      status: 401
      body: '{"error": "Unauthorized"}'

# And endpoint for success (should come after)
- endpoint:
    path: /protected
    response:
      status: 200
      body: '{"message": "You are authenticated!"}'

Useful Tools

OpenAPI Editors

Swagger Editor (online)
- https://editor.swagger.io/
- Validates spec in real-time
VS Code Extension
- "OpenAPI (Swagger) Editor" by 42Crunch
- Autocompletion and validation
Stoplight Studio
- https://stoplight.io/studio
- Visual editor

Spec Validation

# Swagger CLI (Node.js)
npm install -g @apidevtools/swagger-cli
swagger-cli validate openapi.yml

# Spectral (advanced linting)
npm install -g @stoplight/spectral-cli
spectral lint openapi.yml

Spec Generation

# From existing code
# Spring Boot (Java)
# FastAPI (Python) generates automatically
# Express (Node.js) with swagger-jsdoc

Limitations and Workarounds

1. Request Validation

Limitation: Moclojer does not validate requests against the schema.

# Schema defines 'name' as required
requestBody:
  schema:
    required: ['name']

Moclojer accepts any request, even without name.

Workaround: Use tools like Prism for real validation.

2. Multiple Responses by Status

Limitation: Moclojer uses only one example per endpoint.

Workaround: Create separate endpoints for each status code.

3. Callbacks and Links

Limitation: OpenAPI 3.x supports complex callbacks and links, moclojer ignores them.

4. oneOf, anyOf, allOf

Limitation: Complex schemas are not processed.

Workaround: Use explicit example.

OpenAPI vs Native Moclojer YAML

Aspect

OpenAPI

Moclojer YAML

Standard

Industry (portable)

Moclojer-specific

Verbosity

More verbose

More concise

Tools

Many (editors, validators)

Few

Documentation

Spec = documentation

Mock only

Dynamic

Static examples

Dynamic templates

Validation

Schema validation (with tools)

None

Learning curve

Higher (complex spec)

Lower (simple YAML)

When to use OpenAPI:

Already have existing OpenAPI specs
Want to generate SDKs/documentation
Need standardization across teams
API goes beyond mocks (production)

When to use native YAML:

Want dynamic responses with templates
Need quick and simple mocks
Don't need portability
Want minimalist configuration

Combining OpenAPI + Moclojer YAML

You can use both in the same project:

# File structure
project/
├── openapi.yml        # OpenAPI spec (main endpoints)
├── mocks-extras.yml   # Custom mocks with templates
└── mocks-errors.yml   # Error simulations

Start with multiple files:

# Moclojer doesn't support multiple configs directly
# Workaround: combine in one file or use proxy

Alternative: Convert OpenAPI to moclojer YAML:

# Conversion tools (create a script)
# openapi.yml → moclojer.yml

Best Practices

✅ Do

Use examples in all endpoints

responses:
  '200':
    content:
      application/json:
        example:  # ← ALWAYS include!
          id: 1
          name: "John"

Define path parameter types

parameters:
  - name: id
    in: path
    schema:
      type: integer  # → Moclojer uses :id|int

Organize with tags

paths:
  /users:
    get:
      tags: [users]
  /products:
    get:
      tags: [products]

Use $ref to reuse

components:
  schemas:
    Error:
      type: object
paths:
  /users:
    get:
      responses:
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

❌ Avoid

Specs without examples

# ❌ Moclojer doesn't know what to return
responses:
  '200':
    content:
      application/json:
        schema:
          type: object

Complex paths without types

# ⚠️ Without type, accepts any string
/users/{id}:  # Define type: integer!

Troubleshooting

"OpenAPI spec not detected"

Cause: Missing required openapi field.

Solution:

# ✅ Add at the top
openapi: 3.0.0
info:
  title: My API
  version: 1.0.0

"No examples found"

Cause: Spec without example or examples.

Solution: Add explicit examples:

responses:
  '200':
    content:
      application/json:
        example:  # ← Add this!
          data: []

"Path parameters not working"

Cause: Incorrect syntax.

Solution:

# ✅ OpenAPI uses {param}
/users/{id}:

# ❌ Don't use :param in OpenAPI
/users/:id:

Next Steps

Postman Format - Use Postman Collections
YAML Format - Native moclojer syntax
Path Parameters - Dynamic parameters
HTTP Methods - GET, POST, PUT, DELETE

hashtagWhat Is OpenAPI?

hashtagWhy Use OpenAPI with Moclojer?

hashtagOpenAPI Support in Moclojer

hashtagSupported Versions

hashtagAccepted Formats

hashtagQuick Start

hashtag1. Create or Get an OpenAPI Spec

hashtag2. Start Moclojer with OpenAPI

hashtag3. Test

hashtagHow Moclojer Converts OpenAPI

hashtagAutomatic Conversion

hashtagPath Parameters

hashtagQuery Parameters

hashtagRequest Body

hashtagComplete OpenAPI Examples

hashtagExample 1: Simple User API

hashtagExample 2: E-commerce API

hashtagMultiple Responses by Status Code

hashtagHeaders and Content-Type

hashtagSchemas and $ref

hashtagSecurity Schemes (Authentication)

hashtagUseful Tools

hashtagOpenAPI Editors

hashtagSpec Validation

hashtagSpec Generation

hashtagLimitations and Workarounds

hashtag1. Request Validation

hashtag2. Multiple Responses by Status

hashtag3. Callbacks and Links

hashtag4. oneOf, anyOf, allOf

hashtagOpenAPI vs Native Moclojer YAML

hashtagCombining OpenAPI + Moclojer YAML

hashtagBest Practices

hashtag✅ Do

hashtag❌ Avoid

hashtagTroubleshooting

hashtag"OpenAPI spec not detected"

hashtag"No examples found"

hashtag"Path parameters not working"

hashtagNext Steps

hashtagSee Also