Contract API

TSwagger API reference

TSwagger stores OpenAPI contracts used or provided by a project. A definition may be internal or external, restricted or organization-common, and linked to multiple projects without copying revisions.

Namespace/api/swagger

OpenAPI 3.0 and 3.1 are supported. Confirmed secrets and external $ref values are rejected.

All TSwagger calls

Method	Path	Purpose
GET	`/api/swagger/projects`	List projects available to the Swagger credential.Swagger read
GET	`/api/swagger/projects/:projectId/apis`	List bound and organization-common definitions.Swagger read
POST	`/api/swagger/projects/:projectId/apis`	Create definition, project binding, first version, and first revision atomically.Swagger write
GET	`/api/swagger/projects/:projectId/catalog`	Discover linkable organization catalog entries.Swagger read
GET	`/api/swagger/projects/:projectId/apis/:apiId`	Read one definition with versions, revisions, environments, and TDocs links.Swagger read
POST	`/api/swagger/projects/:projectId/api-bindings`	Link an existing catalog API to the project.Swagger write
PATCH	`/api/swagger/projects/:projectId/api-bindings/:bindingId`	Change relationship, alias, pin, URL override, or active state.Swagger write
DELETE	`/api/swagger/projects/:projectId/api-bindings/:bindingId`	Remove a project binding without deleting the canonical definition.Swagger write
POST	`/api/swagger/projects/:projectId/apis/:apiId/versions`	Add a named API version with revision 1.Maintainer Swagger write
POST	`/api/swagger/projects/:projectId/apis/:apiId/versions/:versionId/revisions`	Append an immutable contract revision.Maintainer Swagger write
POST	`/api/swagger/projects/:projectId/apis/:apiId/versions/:versionId/publish`	Publish the expected current revision.Maintainer Swagger write
POST	`/api/swagger/projects/:projectId/apis/:apiId/versions/:versionId/rollback`	Create a new revision copied from an older revision.Maintainer Swagger write
GET	`/api/swagger/projects/:projectId/apis/:apiId/versions/:versionId/spec?format=normalized\|original`	Download normalized JSON or exact submitted YAML/JSON.Swagger read
POST	`/api/swagger/projects/:projectId/api-bindings/:bindingId/environments`	Create an environment; Try it out defaults off.Swagger write
PATCH	`/api/swagger/projects/:projectId/api-bindings/:bindingId/environments/:environmentId`	Edit URL, active state, or Try it out.Swagger write
DELETE	`/api/swagger/projects/:projectId/api-bindings/:bindingId/environments/:environmentId`	Remove an environment.Swagger write

Create an API and first contract

POST /api/swagger/projects/<projectId>/apis
{
  "name": "ANAF RO e-Factura",
  "slug": "anaf-ro-e-factura",
  "description": "External API consumed by the project.",
  "origin": "external",
  "visibility": "restricted",
  "provider": "ANAF",
  "documentationUrl": "https://…",
  "relationship": "consumes",
  "purpose": "Submit and retrieve electronic invoices.",
  "versionLabel": "v1",
  "rawSpec": "openapi: 3.1.0\ninfo:\n  title: …",
  "changeSummary": "Initial official contract"
}

The operation is atomic: invalid OpenAPI, prohibited references, or detected credentials produce an error without leaving a partial definition/binding/version.

Link an existing catalog definition

POST /api/swagger/projects/<projectId>/api-bindings
{
  "apiDefinitionId": "<definition-id>",
  "relationship": "integrates_with",
  "purpose": "Customer identity verification",
  "pinnedVersionLabel": "v2"
}

Add, publish, and roll back revisions

POST /api/swagger/projects/<projectId>/apis/<apiId>/versions/<versionId>/revisions
{ "rawSpec": "<openapi-yaml>", "changeSummary": "Add callback signature" }

POST /api/swagger/projects/<projectId>/apis/<apiId>/versions/<versionId>/publish
{ "expectedRevisionNumber": 3 }

POST /api/swagger/projects/<projectId>/apis/<apiId>/versions/<versionId>/rollback
{
  "targetRevisionNumber": 2,
  "expectedCurrentRevisionNumber": 3,
  "changeSummary": "Restore contract before callback change"
}

Rollback never deletes history. It appends a new immutable revision whose content matches the selected historical revision.

Configure an environment

POST /api/swagger/projects/<projectId>/api-bindings/<bindingId>/environments
{
  "name": "UAT",
  "baseUrl": "https://uat-api.example.com",
  "active": true,
  "tryItOutEnabled": false
}

Environment records are metadata, not a vault.

Never store client secrets, bearer tokens, certificates, API keys, or credentials in URLs or examples. Try it out is disabled by default and inactive environments cannot enable it.