Skip to content
TradeOps Docs

OpenAPI spec and clients

The API is described by an OpenAPI 3.1 document:

How the spec stays accurate

Section titled “How the spec stays accurate”

The spec isn’t written by hand. Scramble builds it from the Laravel code itself: routes, form request validation rules, API resources and controller docblocks. Three checks keep it honest:

  1. No drift. A test regenerates the spec and fails if it differs from the committed openapi/v1.json.
  2. No guessing. The same test fails if any type can’t be worked out, so nothing ends up as an untyped value.
  3. Contract tests. Every API response in the test suite is checked against the spec. If the code returns something the spec doesn’t describe, the test fails.

When you change the API, run this and commit the result with your change:

Terminal window
php artisan scramble:export

Generating a client

Section titled “Generating a client”

Any OpenAPI 3.1 generator works. For the Flutter field app:

Terminal window
npx @openapitools/openapi-generator-cli generate \
  -i https://docs.tradeops.cc/openapi.json \
  -g dart-dio \
  -o lib/api

Pin the spec to a commit or release of the TradeOps repository instead of the live URL, so app builds are repeatable.