code-to-oas

API source code to OpenAPI Specification

Analyzes an API codebase — regardless of language or framework — and produces a complete, valid OpenAPI 3.0.x specification file (openapi.json) from the source code. No existing OAS file is required.

---

Entry Point

1. Identify the root directory. Use the directory the user specifies, or default to the current working directory. If a specific service subdirectory is open in the editor, use that.

2. Detect the language and framework. Scan for indicators without opening every file yet:

   • package.json → Node.js. Check dependencies for express, fastify, koa, hapi, nestjs, @nestjs/core.
   • requirements.txt / pyproject.toml / setup.py → Python. Check for fastapi, flask, django, starlette, tornado.
   • pom.xml / build.gradle → Java/Kotlin. Check for spring-boot, quarkus, micronaut.
   • go.mod → Go. Check for gin, echo, chi, gorilla/mux, fiber.
   • Gemfile → Ruby. Check for rails, sinatra, grape.
   • *.csproj / *.sln → C#/.NET. Check for AspNetCore, WebApi.
   • Any existing partial OAS file (e.g. openapi.yaml, swagger.json) — read it and use it as a starting scaffold, then extend/correct it.

3. Announce the plan.

   "I'll analyze the codebase as a <framework> API and generate openapi.json. I'll read route files, middleware, and model definitions. This may take a moment."

4. Execute the analysis (Steps 1–8 below), then write the OAS file.

---

Step 1 — Discover Route / Controller Files

Locate the files that define HTTP routes or controllers. Use glob and grep patterns matched to the detected framework:

Framework	Look for
Express	Files importing express.Router(), app.get/post/put/delete/patch
FastAPI	Files with @app.get, @router.get, APIRouter()
Flask	Files with @app.route, @blueprint.route
Django	urls.py files, path() / re_path() / url() calls
NestJS	Files with @Controller, @Get, @Post, @Put, @Delete, @Patch
Spring	Files with @RestController, @RequestMapping, @GetMapping, etc.
Gin/Echo/Chi	Files calling r.GET, r.POST, e.GET, r.Route, chi.NewRouter()
Rails	config/routes.rb
Sinatra/Grape	Files with get '/', post '/', resource :name

Read every discovered route file in full. For each route, record:

• HTTP method (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)
• Path string (convert framework-specific syntax to OAS path syntax: :param → {param}, <param> → {param}, {param:int} → {param})
• Handler function name (use as a seed for operationId)
• Middleware applied to this route or router group

---

Step 2 — Extract Operation Details from Handlers

For each route handler identified in Step 1, read the handler implementation. Extract:

Path Parameters

Any segment in the path like {id} is a path parameter. It must appear in parameters with in: path and required: true.

Query Parameters

Look for:

• Express: req.query.foo, destructuring const { foo } = req.query
• FastAPI: function arguments without Body() annotation and not in the path
• Flask: request.args.get('foo')
• Django: request.GET.get('foo')
• Spring: @RequestParam
• Go: c.Query("foo"), r.URL.Query().Get("foo")

Request Body

Look for:

• Express: req.body, req.body.foo
• FastAPI: Body() annotated params, Pydantic model params
• Flask: request.json, request.get_json()
• Django: request.data, request.POST
• Spring: @RequestBody
• Go: c.ShouldBindJSON(), json.NewDecoder(r.Body)

Response Structure

Look for:

• res.json({...}), res.status(200).json({...}) (Express)
• return {...} with type annotations (FastAPI)
• jsonify({...}) (Flask)
• Response(data, ...) (Django REST)
• return ResponseEntity<> (Spring)
• c.JSON(200, ...) (Gin)

Note every distinct status code sent and the shape of each response body.

Headers

Look for authentication headers read from the request:

• req.headers['authorization'], req.headers.authorization
• Authorization: Bearer checks
• Custom headers like x-api-key, x-user-id

---

Step 3 — Identify Authentication / Middleware

Read all middleware files. Look for:

• JWT verification middleware → securityScheme type http, scheme bearer, bearerFormat: JWT
• API key middleware checking a header → securityScheme type apiKey, in: header
• API key middleware checking a query param → securityScheme type apiKey, in: query
• Basic auth → securityScheme type http, scheme basic
• OAuth2 / OIDC → securityScheme type oauth2 or openIdConnect
• Session / cookie auth → securityScheme type apiKey, in: cookie

For each route, determine whether authentication middleware is applied:

• Applied at the router/blueprint level (affects all routes in that group)
• Applied per-route
• Excluded via an allowlist (e.g. /login, /register are public)

Map each route to: authenticated (list the security scheme) or public (no security requirement, or security: [{}]).

---

Step 4 — Discover Data Models / Schemas

Locate model, schema, or DTO definitions:

Framework	Source
Express + Mongoose	mongoose.Schema({...}) definitions
Express + Sequelize	sequelize.define(...) or class models
Express + TypeORM	@Entity class definitions
FastAPI	Pydantic BaseModel subclasses
Flask + SQLAlchemy	db.Model subclasses
Django	models.Model subclasses, serializers.Serializer subclasses
Spring	@Entity, @Document, DTO/POJO classes
Go	type Foo struct { ... } with JSON tags
Rails	ActiveRecord model files, serializer files

For each model/schema, extract:

• All fields with their types
• Required vs optional fields
• Validation constraints: minLength, maxLength, minimum, maximum, pattern, enum, etc.
• Relationships (for reference, not fully expanded in OAS)

Map framework types to OAS types:

Framework type	OAS type + format
String / str / string	type: string
Number / float / Float	type: number, format: float
Int / int / Integer / Long	type: integer, format: int64
Boolean / bool	type: boolean
Date / DateTime / datetime	type: string, format: date-time
Buffer / bytes / BinaryField	type: string, format: binary
Array / List / []Type	type: array, items: <schema>
Object / Dict / Map	type: object
ObjectId / UUID / uuid	type: string, format: uuid
Email / EmailStr	type: string, format: email
Enum	type: string, enum: [...]

---

Step 5 — Discover Server Configuration

Find the server's base URL and port:

• Express: app.listen(PORT) — check PORT env var and its default value
• FastAPI: uvicorn.run(app, host=..., port=...) or Dockerfile/docker-compose.yml
• Django: ALLOWED_HOSTS, runserver port
• Spring: server.port in application.properties/application.yml
• Go: http.ListenAndServe(":PORT", ...)
• Check docker-compose.yml, .env, Dockerfile, Makefile for exposed ports

Check for a URL prefix applied to all routes:

• Express: app.use('/api/v1', router)
• FastAPI: app.include_router(router, prefix='/api/v1')
• Django: path('api/v1/', include(urlpatterns))
• Spring: @RequestMapping('/api/v1')

Record: base URL (e.g. http://localhost:3000) and any API prefix (e.g. /api/v1).

---

Step 6 — Read Supporting Files

Read any existing documentation, README, or config that gives API context:

• README.md — API description, versioning, authentication instructions
• Existing partial openapi.yaml / swagger.json — scaffold to extend
• CHANGELOG.md — API version history
• .env.example — reveals environment variable names and defaults
• package.json version field or pyproject.toml version — API version

Use this to populate:

• info.title
• info.description
• info.version
• info.contact (if present in README)
• info.license (if present)

---

Step 7 — Synthesize the OpenAPI Specification

Build the complete OAS 3.0 document in memory before writing:

7.1 — Construct info

"info": {
  "title": "<API name from README or package.json name field>",
  "description": "<API description from README; CommonMark supported>",
  "version": "<version from package.json / pyproject.toml / git tag>",
  "contact": {           
    "name": "...",
    "email": "..."
  },
  "license": {           
    "name": "...",
    "url": "..."
  }
}

Omit contact and license if not found in the codebase.

7.2 — Construct servers

"servers": [
  {
    "url": "http://localhost:<PORT>",
    "description": "Local development server"
  }
]

Add staging/production servers if found in environment config or README.

7.3 — Construct components.securitySchemes

Define one entry per distinct authentication mechanism found in Step 3. Use descriptive names: BearerAuth, ApiKeyAuth, BasicAuth, OAuth2.

7.4 — Construct components.schemas

One schema per model found in Step 4. Name schemas in PascalCase. Use $ref throughout the document to avoid duplication.

For request schemas (write payloads), exclude readOnly fields like id, createdAt, updatedAt. Mark them "readOnly": true on the base schema instead. Do not create separate CreateFoo and Foo schemas unless the shapes genuinely differ significantly.

7.5 — Construct paths

For each route:

"/path/{param}": {
  "<method>": {
    "operationId": "<camelCase unique id derived from handler name>",
    "summary": "<short description inferred from handler logic>",
    "description": "<longer description if handler is complex>",
    "tags": ["<resource name, e.g. Users, Vehicles, Auth>"],
    "parameters": [
      {
        "name": "param",
        "in": "path",
        "required": true,
        "schema": { "type": "string" }
      }
    ],
    "requestBody": {
      "required": true,
      "content": {
        "application/json": {
          "schema": { "$ref": "#/components/schemas/FooRequest" }
        }
      }
    },
    "responses": {
      "200": {
        "description": "Success",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Foo" }
          }
        }
      },
      "400": { "description": "Bad request — invalid input" },
      "401": { "description": "Unauthorized — missing or invalid credentials" },
      "404": { "description": "Not found" },
      "500": { "description": "Internal server error" }
    },
    "security": [{ "BearerAuth": [] }]
  }
}

Omit requestBody for GET/DELETE/HEAD operations. Omit security on public routes, or set it to [] to override a global default.

operationId rules:

• Must be globally unique and camelCase
• Derive from handler name when available: getVehicleById, createUser
• Fall back to <method><Resource> pattern: getUserById, postVehicle

Tag rules:

• Group by resource noun: /vehicles/* → tag Vehicles
• /auth/* → tag Auth
• List all tags used at the root tags field with short descriptions

Response rules:

• Always include the responses explicitly seen in the code
• Always add 401 to authenticated routes
• Always add 404 to routes with path parameters that fetch a resource
• Always add 400 to routes that accept a request body
• Add 403 if authorization checks (role/ownership) are present in the handler
• Always add 500

7.6 — Apply global security

If the majority of routes are authenticated with the same scheme, apply it globally and override public routes with "security": []:

"security": [{ "BearerAuth": [] }]

If auth is mixed or inconsistent, apply security per-operation only.

---

Step 8 — Write the File

Output location: place openapi.json at the project root, or in an openapi-spec/ subdirectory if one already exists. Never overwrite an existing file without first reading it and confirming the intent with the user (unless the existing file is clearly a scaffold or stub).

Format: JSON. Use 2-space indentation. Order root keys as: openapi, info, servers, tags, paths, components.

After writing, perform a self-review:

• Every $ref resolves to a defined component
• Every {param} in a path has a matching parameter entry with in: path and required: true
• Every operationId is unique
• Every response has a description
• Every in: path parameter has required: true
• No path starts without /

---

Step 9 — Report to the User

After writing the file, output a summary:

OpenAPI Specification Generated
  File:       <relative path to openapi.json>
  Version:    OAS 3.0.x
  Framework:  <detected framework>
  Paths:      <N> endpoints across <M> route files
  Tags:       <list of tags>
  Schemas:    <N> component schemas
  Security:   <scheme names, or "None detected">

Coverage notes:
  - <any routes that were ambiguous or skipped, and why>
  - <any response bodies that could not be inferred>
  - <any assumptions made that the user should verify>

---

Framework-Specific Notes

Express (Node.js)

• Route files often export a Router and are mounted in a central app.js or server.js — always read the entry point to find all mounts and their prefixes.
• Middleware like authenticate or verifyToken applied with .use() before route groups means all routes in that group are protected.
• req.params, req.query, req.body map to path/query/requestBody.

FastAPI (Python)

• Type annotations on route function parameters are the source of truth for schemas — use them directly.
• response_model=Foo on the decorator tells you the response schema.
• status_code=201 on the decorator overrides the default 200.
• Pydantic BaseModel subclasses become components.schemas directly.

Flask (Python)

• Blueprint url_prefix combines with @blueprint.route path.
• Flask-RESTX / Flask-RESTful Resource classes map methods to HTTP verbs.
• Marshmallow schemas, if present, are the source of truth for serialization/deserialization shapes.

Django REST Framework

• ViewSet routers generate CRUD routes automatically — infer them from router.register() calls.
• serializers.py files define the schema shapes.
• permission_classes on a view define authentication requirements.

NestJS (TypeScript)

• DTOs (Data Transfer Objects) annotated with class-validator decorators become request schemas.
• @ApiProperty() decorators (if Swagger module is used) carry schema metadata — prioritize these.
• Guard decorators (@UseGuards(JwtAuthGuard)) mark routes as authenticated.

Spring Boot (Java/Kotlin)

• @RequestBody, @PathVariable, @RequestParam map directly to OAS concepts.
• Return type of controller methods (including ResponseEntity<Foo>) defines the response schema.
• @Valid / @Validated on request body parameters implies validation constraints are on the DTO class fields.

Go (Gin / Echo / Chi)

• Struct tags (json:"field_name" binding:"required") define field names and required constraints.
• c.ShouldBindJSON(&dto) or c.BindJSON(&dto) identifies the request body type.
• Middleware registered with r.Use(AuthMiddleware) before route groups marks those routes as authenticated.

---

General Constraints

• Do not fabricate routes, schemas, or responses that are not evidenced in the source code. If a handler's response body is unclear, use type: object with additionalProperties: true and note the ambiguity.
• Do not modify any source code files. This skill is read-only with respect to the codebase.
• Prefer $ref over inline schemas for any object used more than once.
• Use OAS 3.0.x (e.g. openapi: "3.0.3"), not 2.0 (Swagger) or 3.1, unless the user explicitly requests otherwise.
• Always include operationId — it is required for downstream tooling such as 42Crunch audit and scan.
• Use nullable: true (OAS 3.0 style) for fields that can be null, not type: ["string", "null"] (OAS 3.1 style).
• Keep schema names in PascalCase, operationId values in camelCase, and tag names in Title Case.