---
title: "OpenAPI Spec Generation"
description: "OpenAPI Specification Generation"
url: https://docs.stackhawk.com/platform/api-discovery/oas-generation/
---

# OpenAPI Spec Generation

> **Note:** *This feature is available on the StackHawk [Scale plan](https://www.stackhawk.com/pricing/).*

Most APIs lack OpenAPI specifications, which makes comprehensive security testing difficult. OpenAPI Spec Generation solves this by automatically generating [OpenAPI Specifications](https://swagger.io/specification/) from your source code, enabling you to test APIs that would otherwise remain untested.

Generated specs can be reviewed in the Attack Surface view or used directly in HawkScan via [OpenAPI Configuration](https://docs.stackhawk.com/hawkscan/configuration/openapi-configuration/).

[OAS Docs Video](https://fast.wistia.net/embed/iframe/jl8jb0llqf?web_component=true\&seo=false)

## How It Works

StackHawk analyzes your source code directly from connected repositories—no traffic monitoring or manual documentation required.

1. **Code Analysis**: StackHawk parses your codebase to identify API endpoints, routes, parameters, and request/response structures
2. **Spec Generation**: AI processes the code analysis to generate OpenAPI 3.0 compliant specifications
3. **Continuous Updates**: Repositories are reanalyzed weekly and after API Discovery processing to keep specs current

This source-code approach provides complete endpoint coverage, including paths that traffic-based tools miss: error handlers, authentication flows, and endpoints not yet in production.

## Using Generated Specs

The repository must be **mapped to an application** in StackHawk to use its generated spec in a scan.

### From Attack Surface

Click the OAS pill in the Attack Surface table to open the slideout.

![generated oas attack surface pills](https://docs.stackhawk.com/images/platform/api-discovery/oas-detection/oas-attack-pills.png)

From there, use the dropdown to select a generated spec, review endpoints, search, or filter by verb.

![generated oas attack surface](https://docs.stackhawk.com/images/platform/api-discovery/oas-detection/oas-attack-panel.png)

### From Application Details

Go to the OAS tab to see all specs for the app. Each entry shows the repo, path, and a `hawk://` URI. Click a spec to open its slideout for details.

Download the file or copy the `hawk://` URI. Add it to your `stackhawk.yaml` under `openApiConf.filePaths` to use it in scans:

```yaml
app:
  openApiConf:
    filePaths:
      - hawk://<oas-id>
```

![generated OAS from application details](https://docs.stackhawk.com/images/platform/api-discovery/oas-detection/oas-app-slideout.png)

### Platform Hosted Specifications

StackHawk-generated specs can be included in scans using the `usePlatform: true` configuration. Check the box next to a generated specification to include it when running HawkScan.

![Select OpenAPI specifications to scan with from the platform](https://docs.stackhawk.com/images/platform/api-discovery/oas-detection/oas-platform-hosted.png)

```yaml
app:
  openApiConf:
    usePlatform: true
```

HawkScan requires at least one checked specification for the scanned application. The platform-hosted specs will be downloaded and used to drive the scan.

### On the Scan Details Panel

An OAS pill in the Scans table indicates the scan used a StackHawk-generated OpenAPI spec. Opening the scan shows the Scan Details panel with “Generated Open API Spec” confirmation.

![generated-oas-scan-details](https://docs.stackhawk.com/images/platform/api-discovery/oas-detection/oas-scan-details.png)

## Supported Languages & Frameworks

Spec generation is available for repositories using these language/framework combinations:

| Language | Framework | Status |
| - | - | - |
| C# | [ASP.Net Core](https://learn.microsoft.com/en-us/aspnet/core/) | Coming Soon |
| Java | [Spring Framework](https://spring.io/) | Beta |
| Java | [Micronaut](https://micronaut.io/) | Alpha |
| JavaScript | [ExpressJS](https://expressjs.com/) | Beta |
| JavaScript | [NodeJS](https://nodejs.org/) | Alpha |
| Python | [Flask](https://flask.palletsprojects.com/) | Alpha |
| Scala | [Play Framework](https://www.playframework.com/) | Alpha |
| TypeScript | [ExpressJS](https://expressjs.com/) | Beta |

## Disabling OpenAPI Specification Generation

Spec generation uses AI to analyze code structure. Code analysis results (not raw source code) are processed by LLM services. No customer data is used for AI model training.

To disable this feature, go to **Settings → Org Settings → HawkAI** and toggle off `OpenAPI Spec Gen`.

> **Warning:** Disabling this feature stops automatic spec generation. You’ll need to provide specs manually to test APIs without existing documentation.