Skip to main content

Generating OpenAPI Specification (OAS) using Code Bolt

About Code Bolt​

Code Bolt is APIsec's tool that reads application source code and automatically generates an OpenAPI specification — a structured file that lists all the API endpoints, their HTTP methods, parameters, and request/response schemas. APIsec then uses this spec to run security scans.

  • scans your repo on push/schedule
  • generates OpenAPI output
  • opens a pull request with generated files
  • uploads the spec to APIsec and tracks application state across runs(unless dry-run).

Prerequisites​

  • A GitHub repository with your application code
  • APIsec endpoint and token
  • Permission to add GitHub repository secrets

Step 1: Add GitHub secrets​

In your repo, go to Settings -> Secrets and variables -> Actions and add:

  • API_DISCOVERY_ENDPOINT
  • API_DISCOVERY_TOKEN

Step 2: Add the workflow​

Create .github/workflows/api-discovery.yml:

name: API Discovery

on:
  push:
    branches: [main]

jobs:
  discover:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: apisec-inc/apisec-bolt-code-discovery-github-action@v0.1.5
        with:
          api-endpoint: ${{ secrets.API_DISCOVERY_ENDPOINT }}
          api-token: ${{ secrets.API_DISCOVERY_TOKEN }}

Step 3: Optional inputs (most common)​

- uses: apisec-inc/apisec-bolt-code-discovery-github-action@v0.1.5
  with:
    api-endpoint: ${{ secrets.API_DISCOVERY_ENDPOINT }}
    api-token: ${{ secrets.API_DISCOVERY_TOKEN }}
    repo-path: ./backend
    host-url: https://api.example.com
  • repo-path: scan a subfolder (helpful for monorepos)
  • host-url: sets the OpenAPI server URL when the parser cannot extract a host from your code. Recommended — without it, state isn't saved across runs, so each run creates a new application in APIsec instead of updating the existing one.
  • dry-run: true: generate spec without API upload

Step 4: Run and verify​

Push a commit to main (or trigger the workflow).

On success, Code Bolt creates/updates:

  • apisec-bolt-code-discovery/openapi_spec.yaml
  • apisec-bolt-code-discovery/state.yaml

It also opens a PR with the generated changes.

Supported frameworks​

Code Bolt auto-detects and parses:

  • Java: Spring Boot, Micronaut, Argos
  • Python: FastAPI, Flask, Django
  • Node.js: Express
  • Go: Gin
  • .NET: ASP.NET Core

Argos users (optional env vars)

If your Java service uses Argos and you want better servers population in OpenAPI, you can set:

  • ARGOS_DNS_MAPPING_PATH
  • ARGOS_APPLICATION_NAME (optional override)

If these are not set, path discovery still works; only servers enrichment may be limited.

Quick troubleshooting​

  • No frameworks detected
    • Confirm code exists under the scanned path (repo-path or repo root).
  • OpenAPI generated but wrong/empty server URL
    • Set host-url input, or Argos env vars if applicable.
  • Monorepo not scanning the right service
    • Point repo-path to the correct service folder.
  • Want to test without upload
    • Set dry-run: true.

Important Considerations​

  • Generated files are expected to be committed through the PR.
  • state.yaml stores discovery state IDs and is safe to commit (no secrets).
  • Secrets must stay in GitHub Secrets, not in repository files.