OpenAPI Specification

The CourseForge API is fully documented using the OpenAPI 3.1 specification, enabling automatic SDK generation and integration with API tools.

What is OpenAPI? OpenAPI (formerly Swagger) is an industry-standard specification for describing RESTful APIs.

Accessing the Specification

Download OpenAPI JSON

curl https://courseforge.caringai.app/api/openapi > courseforge-api.json

View in Browser

Visit: https://courseforge.caringai.app/api/openapi

The specification includes:

All API endpoints
Request/response schemas
Authentication methods
Error codes
Examples

Using with API Tools

Postman

Open Postman
Click Import
Select Link tab
Enter: https://courseforge.caringai.app/api/openapi
Click Continue → Import

Now you can test all endpoints directly from Postman.

Swagger UI

View interactive documentation:

docker run -p 8080:8080 \
  -e SWAGGER_JSON_URL=https://courseforge.caringai.app/api/openapi \
  swaggerapi/swagger-ui

Visit: http://localhost:8080

Insomnia

Open Insomnia
Click Create → Import From
Select URL
Enter: https://courseforge.caringai.app/api/openapi
Click Fetch and Import

Generating Client SDKs

JavaScript/TypeScript

npx @openapitools/openapi-generator-cli generate \
  -i https://courseforge.caringai.app/api/openapi \
  -g typescript-fetch \
  -o ./courseforge-sdk

Python

pip install openapi-python-client

openapi-python-client generate \
  --url https://courseforge.caringai.app/api/openapi \
  --output-path ./courseforge-sdk

Ruby

openapi-generator generate \
  -i https://courseforge.caringai.app/api/openapi \
  -g ruby \
  -o ./courseforge-sdk

Go

openapi-generator generate \
  -i https://courseforge.caringai.app/api/openapi \
  -g go \
  -o ./courseforge-sdk

Java

openapi-generator generate \
  -i https://courseforge.caringai.app/api/openapi \
  -g java \
  -o ./courseforge-sdk

Example Generated Usage

After generating an SDK:

TypeScript:

import { Configuration, CoursesApi } from './courseforge-sdk'

const config = new Configuration({
  apiKey: 'YOUR_API_KEY',
  basePath: 'https://courseforge.caringai.app/api/v1'
})

const api = new CoursesApi(config)

// List courses
const courses = await api.listCourses()

// Create course
const newCourse = await api.createCourse({
  name: 'My Course',
  description: 'Course description'
})

Python:

from courseforge_sdk import ApiClient, Configuration, CoursesApi

config = Configuration(
    api_key={'Authorization': 'Bearer YOUR_API_KEY'},
    host='https://courseforge.caringai.app/api/v1'
)

with ApiClient(config) as client:
    api = CoursesApi(client)

    # List courses
    courses = api.list_courses()

    # Create course
    new_course = api.create_course({
        'name': 'My Course',
        'description': 'Course description'
    })

Mock Servers

Generate a mock server for testing:

docker run -p 4010:4010 \
  -v $(pwd)/courseforge-api.json:/openapi.json \
  stoplight/prism:4 \
  mock -h 0.0.0.0 /openapi.json

Test against the mock server:

curl http://localhost:4010/api/v1/courses

Validation

Validate your API requests against the spec:

npx @stoplight/spectral-cli lint courseforge-api.json

IDE Integration

VS Code

Install the OpenAPI (Swagger) Editor extension to:

View spec with syntax highlighting
Validate spec in real-time
Preview documentation
Autocomplete when editing

JetBrains IDEs

Built-in OpenAPI support:

Open .json or .yaml spec files
Get autocomplete and validation
Generate code from spec

Contributing

Found an error in the specification?

File an issue: GitHub Issues
Email: api@courseforge.com

Changelog

The OpenAPI spec is versioned with the API. Major changes:

v1.0.0 (2025-01-01): Initial release
All changes logged in spec info.version