OpenAPI sync

Apply changes#

Apply a stored OpenAPI 3.0, 3.1, or 3.2 document to APIs and Endpoints. The server parses structly.yaml and returns its updated content. stly registers, plans, and applies approved changes using a source file and structly.yaml. The Web UI can also register documents, submit new sources, and approve selected changes (Web UI).

1. Register the file with register. Without --repository, this creates a standalone OpenAPI document.
2. Choose the API and providing Service with import-plan and review the change IDs. Planning saves nothing.
3. Use the same file, choices, and plan token to import approved changes.

stly spec-documents register openapi/orders.yaml --name Orders --manifest structly.yaml
stly spec-documents import-plan openapi/orders.yaml --manifest structly.yaml --create-api '{"name":"Orders","handle":"orders"}' --none
stly spec-documents import openapi/orders.yaml --manifest structly.yaml --create-api '{"name":"Orders","handle":"orders"}' --none --approve-all --if-match '"import-plan:…"'

Before registration or application, a read-only server request verifies the manifest server, Organization, Repository, and document. stly writes the registration key to the file first, then merges the document ID after registration. Retry with the same key after a response or file-save failure. The registration request also pins the verified Organization ID, rejecting registration if the connection changes after the check. Without --manifest, stly searches upward from the current directory; a new registration creates the file in the current directory. JSON --input mode with an explicit document ID remains available. --dry-run shows the sequence without preflight requests, credential access, or file changes.

Example first-import request. Replace content and manifest with the actual text of each file.

{
  "content": "OpenAPI source text",
  "manifest": "structly.yaml text",
  "path": "openapi/orders.yaml",
  "api": {"create": {"name": "Orders", "handle": "orders"}},
  "service": null
}

For the first import, set api to {"id":"…"} for an existing API or {"create":{"name":"…","handle":"…"}} for a new API. For service, use the same form for an existing or new Service, or null to explicitly leave it unlinked. The manifest's service_id also supplies this choice. A document and API have a one-to-one link. You can omit api after linking them.

Plans and approvals#

The plan's data includes plan_token, applicable, changes, items, deletion_candidates, warnings, and errors. If applicable is false, fix the errors and make another plan.

Each change's fields shows current and new values, overwrites lists fields to replace, and requires lists change IDs that must be approved together. Put only the selected IDs in the apply request's approved array. The first import also requires approval of the API and Service choices. Unapproved values stay unchanged and appear again in the next plan. Each import also saves the submitted source text. If the selected result fails existing Catalog validation, SYNC_INVALID rolls back the entire import.

Pass the plan's etag or data.plan_token to --if-match. If related documents, APIs, or Endpoints change, HTTP 412 requires a new plan. --dry-run only prints a local request plan without making an HTTP request.

Recovery and existing Endpoints#

• When a mapping is missing but the server's source document and operationId match, recover restores the ID. Field differences still require approval.
• Manual Endpoints in the same API with matching Method and Path appear as link_candidate. The first import also considers unassigned Endpoints. A unique candidate is never linked automatically.
• To link one, provide an operationId-to-Endpoint-ID mapping in link, make a new plan, and approve :link.
• To rename an operationId, provide the old-to-new mapping in rename and replan. Moving requires the declaration to be absent from the previous document and approval of :move.
• A missing mapped ID produces ENDPOINT_NOT_FOUND. Add the operationId to recreate, replan, and approve :recreate to create a new Endpoint.
• Removed operations appear in deletion_candidates. Confirm deletion or source release separately.
• Conflicting manifest and server identity produces MANIFEST_MISMATCH. Use manifest to check the server values and correct your file.

The server preserves other manifest entries and comments. If saving the returned file fails after import, the next plan can recover mappings from the server's source records.

Conversion and source release#

Every operation needs a unique operationId. External file or URL $ref values are unsupported. OpenAPI 3.2 query and additionalOperations operations and in: querystring Parameters cannot be stored and block import. Unstored content such as security, tags, and examples is reported in warnings. Existing Endpoint examples and External References are preserved.

Endpoints that have a source can be edited in the Web UI and with stly. To change their API membership, release the source first. Releasing the source keeps the values and API membership and turns the Endpoint into a manual record. Use 스펙 출처 해제 in the Web UI or:

stly endpoints release-source <endpoint-id> --if-match '"ETag from the Endpoint detail lookup"'

Web UI#

The Web UI runs the same plan and approval steps on screen. It uses the server's structly.yaml instead of a local file.

1. Register documents without a Repository and see the list from OpenAPI 문서 (OpenAPI documents) at the top of APIs. Open Repository documents from the spec documents on the Repository detail.
2. Registration opens the change review right away. For a document that is already linked, open 새 원문 제출·변경 승인 (submit new source and approve changes).
3. For the first import, choose a new or existing API, and a providing Service (none, existing, or new). For a linked document, 현재 제공 Service 유지 (keep current providing Service) is the default.
4. Keep the stored source, paste a new one, or load a file, then select 변경 계획 조회 (view change plan).
5. Check the changes to apply. Add required changes with 함께 선택 (select together) in the notice. After choosing a link candidate or a previous operationId, select 계획 다시 조회 (view plan again).
6. Select 선택한 변경 N개와 원문 반영 (apply N selected changes and the source), then download the updated structly.yaml. Keep it next to the source when you work on the same document with stly.

• After viewing a plan, changing the source or choices blocks applying until you view the plan again.
• If another change was saved first (HTTP 412), view the plan again. If no response arrives, the request is not resent automatically; view the plan again to check whether it was applied.
• Resending a registration after a lost response reuses the same registration key, so the document is not created twice.
• You can download the server's structly.yaml at any time from OpenAPI 문서 on the API detail or from a Repository spec document detail.
• Export of Catalog values to the source runs in stly.

Export Catalog values to OpenAPI#

Select API Metadata, Base URLs, and Endpoint summaries and descriptions from the Catalog to apply to the source. The providing Service changes only the manifest. Export never updates the server Catalog or stored source.

stly spec-documents export-plan openapi/orders.yaml --manifest structly.yaml
stly spec-documents export openapi/orders.yaml --manifest structly.yaml --approve api.name,op:getOrder:summary --if-match '"export-plan:…"'

• Keep the source within the manifest directory. The server resolves its document ID from the manifest; the explicit ID plus --file form remains supported. Without --manifest, stly searches upward from the current directory for structly.yaml.
• changes contains supported changes: current is the normalized source value and new is the Catalog value. unsupported lists differences to edit in the source. Routes, requests, responses, operation creation or deletion, OAS 3.0 info.summary, variable-containing servers, and shared references or aliases are not rewritten automatically.
• --approve accepts comma-separated change IDs. --approve-all approves only supported changes within the same plan token; a changed token stops the command before applying.
• If either source or manifest hash changes after reading, originals are kept and results are saved beside each file with .new appended, then the command fails. Existing .new files are never overwritten. Both inputs must be regular files. Each is replaced by renaming a temporary file, so a second-file replacement failure may leave the first file updated. Check the local files identified by the error.
• --dry-run prints the request plan without HTTP or file changes. JSON --input mode cannot be combined with --file and only prints the response. Omitting content uses the stored source.
• Review and save export results, then import to align the stored server source. Once supported fields match, their import differences disappear.

Confirm the providing Service#

Use the ETag from apis service get with set-service. In the Web UI, use 제공 Service on the API detail (API).

stly apis service get <api-id>
stly apis set-service <api-id> --service <service-id> --if-match '"Service ETag"'
stly apis set-service <api-id> --none --if-match '"Service ETag"'

Specify exactly one of --service and --none. --none explicitly leaves the API unlinked. A stale ETag returns 412.

Approving authentication changes#

api.security changes the API scheme definitions and common requirements. op:<operationId>:security changes an Endpoint override. Inspect affected Endpoints and before/after values in security_impacts. Approve required definition and reference changes together. Combinations that leave dangling references in unapproved, manual, or deletion-candidate Endpoints are rejected.

Authentication export differences are reported as unsupported. Edit the source or approve the import direction instead. Exporting other supported fields preserves authentication source nodes. Structly does not log in, issue tokens, or contact authentication servers.