08.05 The OpenAPI Documentation

Why this is a reference article

This article documents how to find and use SimpleRisk's API documentation. The documentation itself is in-product (the Swagger UI page is always current with the install's actual API surface); this article tells you where to find it and how to get value from it.

Where to find it

The Swagger UI is rendered at:

https://your-simplerisk-instance.example.com/api/v2/documentation.php

(Some installs may also expose /api/v2/documentation/ as a directory-style alternative; both render the same Swagger UI.)

The page is publicly accessible by default — no authentication required to read the documentation. To make calls from the Try it out feature, you'll need an API key (the page lets you paste it into an authentication field).

What's on the page

The Swagger UI lists every documented endpoint, grouped by tag. Typical groups:

Risks — risk CRUD plus per-risk operations (submit, review, mitigate, close, comment).
Governance — frameworks, controls, documents, exceptions.
Compliance — control tests, audits.
Assets — asset CRUD.
Admin — administrative operations.
AI — AI Extra endpoints (when the Extra is active).
Reporting — report-data endpoints.
Security — auth-related endpoints.
UI — endpoints supporting the web UI.
General — endpoints that don't fit the other groups.

Each endpoint shows:

HTTP method and path (e.g., GET /api/v2/risks, POST /api/v2/risks/submit).
Summary — one-line description.
Parameters — for GET endpoints, the query parameters and their types. For POST/PATCH endpoints, the request body schema.
Responses — the success response (typically 200 or 204) and any documented error responses (400, 403, 404, etc.).
Try it out button — opens an in-page form to make the call against the live API.

Generation: from annotations in the code

The Swagger UI is auto-generated from OpenAPI annotations in the SimpleRisk source. Each endpoint in simplerisk/api/v2/index.php has a corresponding @OA\Get(...) / @OA\Post(...) / etc. annotation block in simplerisk/api/v2/documentation/ .php. The annotations include the endpoint's summary, parameters, request schema, response schema, and security requirements.

This means the documentation is always in sync with the running install's API surface. If an endpoint doesn't appear in the Swagger UI, it doesn't exist in this install. If an endpoint's documented shape differs from the live behavior, that's a documentation bug — file it, but in the meantime trust the live API.

For Extras: the Extras' endpoints get their own annotations and appear in the Swagger UI when the relevant Extra is active. An install with the AI Extra inactive won't show the AI endpoints.

Using the page for integration development

Browse the catalog

For a new integration, browse the Swagger UI to find what's available. Filter by tag (Risks, Governance, etc.); read the endpoint summaries; click into endpoints to see parameters and response shapes.

The browse-then-build workflow beats "guess at the endpoint and see what happens." Most integration developers find the endpoints they need within a few minutes of browsing.

Test endpoints with Try it out

For each endpoint:

Click the endpoint to expand its details.
Click Try it out.
Fill in parameters (query parameters, path parameters, request body).
Authenticate — the page typically has an Authorize button at the top where you paste your API key (it'll be added as the X-API-KEY header to subsequent test calls).
Click Execute.
The page shows the curl command, the request URL, the response status, the response headers, and the response body.

This is the fastest way to iterate on integration development: try the call, see the response, adjust, repeat.

Don't test mutating calls (POST, PATCH, DELETE) against production from the docs page. Use a non-production instance, or accept the consequences (you'll create / modify / delete real data).

Copy the curl command

After Try it out, the Swagger UI shows the exact curl command for the call. Copy it; adapt to your integration's HTTP client library. This is the fastest path from "I see what I need to do" to "my integration code does it."

Export to Postman

Many programs prefer Postman for API exploration over Swagger UI. The OpenAPI specification rendered in Swagger UI can be exported as a Postman collection; see Using the Postman Collection.

Reading the OpenAPI specification

Endpoint annotation example

A typical endpoint annotation in simplerisk/api/v2/documentation/risks.php:

/**
 * @OA\Get(
 *     path="/risks/{id}",
 *     summary="Get a single risk by ID",
 *     operationId="getRiskById",
 *     tags={"Risks"},
 *     security=},
 *     @OA\Parameter(
 *         name="id",
 *         in="path",
 *         required=true,
 *         description="The risk ID",
 *         @OA\Schema(type="integer")
 *     ),
 *     @OA\Response(
 *         response=200,
 *         description="OK",
 *         @OA\JsonContent(ref="#/components/schemas/Risk")
 *     ),
 *     @OA\Response(response=403, description="Forbidden"),
 *     @OA\Response(response=404, description="Not Found")
 * )
 */

This produces the Swagger UI block for GET /api/v2/risks/{id} showing the path parameter, the auth requirement, and the success/error responses. The Risk schema referenced via $ref is defined elsewhere in the documentation files and renders inline in the UI.

Schema definitions

Complex types (Risk, Mitigation, Control, etc.) are defined as reusable schemas in the documentation files. The Swagger UI shows the schema definitions in a collapsible Schemas section at the bottom; each schema lists its fields, types, and constraints.

For programs writing strongly-typed integration clients (TypeScript, Java, C#), the OpenAPI spec can be downloaded and fed to a code generator (openapi-generator, swagger-codegen) to produce typed client SDKs.

Downloading the raw spec

The raw OpenAPI JSON / YAML is typically available at /api/v2/documentation/openapi.json (or similar — check the install's actual path). This is what the Swagger UI consumes; you can also feed it directly to other tools (Postman import, code generators, custom documentation).

Common issues

"I can't find an endpoint I expected to exist"

It might not exist; SimpleRisk's API doesn't cover every UI operation. File a feature request via Getting Help if a gap blocks your integration.

"The Swagger page is empty or shows fewer endpoints than expected"

Possible causes:

The relevant Extras aren't active (Extras' endpoints only appear when their Extra is active).
The OpenAPI annotations weren't generated for some endpoints (rare; usually a bug).
The Swagger UI's filter is set; clear filters and reload.

"Try it out works but my integration gets 401"

The Try it out's authentication uses a key you paste in; your integration's authentication might be:

Missing the X-API-KEY header.
Using a different (revoked) key.
Hitting /api/v1/ instead of /api/v2/.

Compare your integration's request to the Swagger-generated curl command.

"The documented response shape doesn't match what I'm getting"