OpenAPI 동기화

반영 순서#

보관한 OpenAPI 3.0·3.1·3.2 문서를 API와 Endpoint에 반영합니다. 서버가 structly.yaml을 해석하고 갱신본을 반환합니다. stly는 원문 파일과 structly.yaml로 등록·계획·승인 반영을 수행합니다. Web UI에서도 등록·새 원문 제출·변경 선택 승인을 할 수 있습니다(Web UI).

1. register로 파일을 등록합니다. --repository가 없으면 독립 OpenAPI입니다.
2. import-plan으로 API·제공 Service를 선택하고 변경 ID를 확인합니다. 저장하지 않습니다.
3. 같은 파일·선택 옵션과 계획의 토큰으로 승인한 변경만 import합니다.

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:…"'

서버는 실제 등록·반영 전에 읽기 전용 사전 조회로 manifest의 서버·Organization·Repository와 문서를 확인합니다. stly는 등록 키를 파일에 먼저 기록하고 등록 뒤 문서 ID를 병합합니다. 응답·파일 저장에 실패하면 같은 키로 재시도합니다. 사전 확인한 Organization ID는 등록 요청에도 고정해 조회 이후 연결이 바뀐 경우 등록을 거부합니다. --manifest를 생략하면 현재 디렉터리부터 상위로 탐색하고, 새 등록은 현재 디렉터리에 파일을 만듭니다. 문서 ID를 직접 쓰는 JSON --input 방식도 유지합니다. --dry-run은 사전 조회·credential 접근·파일 변경 없이 순서만 표시합니다.

최초 반영의 요청 예입니다. content와 manifest에는 각 파일의 실제 원문 문자열을 넣습니다.

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

첫 반영은 api에 기존 API의 {"id":"…"} 또는 새 API의 {"create":{"name":"…","handle":"…"}}를 지정합니다. service에는 같은 형태의 기존·새 Service 또는 명시적 미연결인 null을 지정합니다. manifest의 service_id도 선택으로 사용합니다. 문서와 API는 1:1이며 연결 후에는 api를 생략할 수 있습니다.

계획과 승인#

계획의 data에는 plan_token·applicable·changes·items·deletion_candidates·warnings·errors가 있습니다. applicable:false이면 오류를 고친 뒤 다시 계획합니다.

각 변경의 fields는 현재 값과 새 값, overwrites는 덮어쓸 필드, requires는 함께 승인할 변경 ID를 나타냅니다. 반영 본문의 approved에는 선택한 ID만 넣습니다. 첫 반영에는 API·Service 선택의 변경 ID를 함께 승인해야 합니다. 승인하지 않은 값은 유지하고 다음 계획에서 다시 보고합니다. 제출 원문은 반영마다 함께 저장됩니다. 승인 결과가 기존 Catalog 검증에 실패하면 SYNC_INVALID로 전체 반영을 되돌립니다.

계획의 etag 또는 data.plan_token을 --if-match에 넣습니다. 관련 문서·API·Endpoint 등이 바뀌면 HTTP 412이므로 다시 계획합니다. --dry-run은 HTTP 요청 없이 로컬 요청 계획만 출력합니다.

복구와 기존 Endpoint#

• 매핑이 없어도 서버의 출처 문서·operationId가 일치하면 recover로 ID를 복구합니다. 필드 차이는 별도 승인이 필요합니다.
• 같은 API의 출처 없는 Endpoint가 Method·Path와 일치하면 link_candidate로 표시합니다. 첫 반영은 미소속 Endpoint도 후보입니다. 후보가 하나여도 자동 연결하지 않습니다.
• 연결하려면 요청의 link에 operationId → Endpoint ID를 지정하고 다시 계획한 뒤 :link를 승인합니다.
• operationId를 바꿀 때는 rename에 이전 ID → 새 ID를 지정하고 다시 계획합니다. 이동은 이전 문서에 선언이 없어야 하며 :move 승인이 필요합니다.
• 존재하지 않는 매핑 ID는 ENDPOINT_NOT_FOUND입니다. recreate 배열에 operationId를 지정하고 재계획 후 :recreate를 승인해 새로 만듭니다.
• 문서에서 사라진 operation은 deletion_candidates로 보고합니다. 삭제·출처 해제는 별도로 확정합니다.
• manifest와 서버의 식별 정보가 다르면 MANIFEST_MISMATCH입니다. manifest 명령으로 서버 기준을 확인해 파일을 고칩니다.

서버는 다른 manifest 항목과 주석을 보존합니다. 반영 후 파일을 저장하지 못해도 다음 계획에서 서버 출처로 매핑을 복구할 수 있습니다.

변환과 출처 해제#

operation마다 고유한 operationId가 필요합니다. 외부 파일·URL의 $ref는 지원하지 않습니다. OpenAPI 3.2의 query·additionalOperations operation과 in: querystring Parameter는 저장할 수 없어 반영을 막습니다. 저장하지 않는 security·tags·예제 등은 warnings로 보고합니다. 기존 Endpoint 예제와 External Reference는 유지합니다.

출처가 있는 Endpoint도 Web UI·stly에서 필드를 수정할 수 있습니다. API 소속을 바꾸려면 출처를 먼저 해제합니다. 출처를 해제하면 값과 API 소속을 유지하며 수동 기록으로 바뀝니다. Web의 스펙 출처 해제 또는 다음 명령을 사용합니다.

stly endpoints release-source <endpoint-id> --if-match '"Endpoint 상세 조회의 ETag"'

Web UI#

Web UI는 같은 계획·승인 절차를 화면으로 실행합니다. 원문 파일 대신 서버 기준 structly.yaml을 사용합니다.

1. Repository 없는 문서는 APIs 화면 위쪽의 OpenAPI 문서에서 등록하고 목록을 확인합니다. Repository 소속 문서는 Repository 상세의 스펙 문서에서 엽니다.
2. 등록하면 바로 변경 검토 화면이 열립니다. 이미 연결된 문서는 새 원문 제출·변경 승인으로 엽니다.
3. 처음 반영하는 문서는 새 API 생성 또는 기존 API와, 제공 Service(없음·기존·새 Service)를 고릅니다. 연결된 문서는 현재 제공 Service 유지가 기본입니다.
4. 저장된 원문을 그대로 쓰거나 새 원문을 붙여 넣거나 파일로 불러온 뒤 변경 계획 조회를 누릅니다.
5. 반영할 변경을 체크합니다. 함께 승인해야 하는 변경은 안내의 함께 선택으로 더합니다. 연결 후보·이전 operationId 후보를 고르면 계획 다시 조회를 누릅니다.
6. 선택한 변경 N개와 원문 반영을 누른 뒤 갱신된 structly.yaml을 내려받습니다. stly로 같은 문서를 다룰 때 원문 옆에 둡니다.

• 계획을 조회한 뒤 원문이나 선택을 바꾸면 다시 조회하기 전까지 반영할 수 없습니다.
• 다른 변경이 먼저 저장되면(HTTP 412) 계획을 다시 조회합니다. 응답을 받지 못하면 자동으로 다시 보내지 않으며, 계획을 다시 조회해 반영 여부를 확인합니다.
• 등록 응답을 받지 못했을 때 다시 보내면 같은 등록 키를 사용하므로 문서가 두 번 만들어지지 않습니다.
• API 상세의 OpenAPI 문서와 Repository 스펙 문서 상세에서 언제든 서버 기준 structly.yaml을 내려받을 수 있습니다.
• Catalog 값을 원문으로 내보내는 export는 stly에서 실행합니다.

Catalog 값을 OpenAPI로 내보내기#

서버 Catalog의 API Metadata·Base URL·Endpoint 요약·설명을 선택 승인해 원문에 반영합니다. 제공 Service는 manifest만 갱신합니다. export는 서버 Catalog와 저장 원문을 바꾸지 않습니다.

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:…"'

• 파일은 manifest 디렉터리 안에 둡니다. 문서 ID는 서버가 manifest에서 확인하며, ID와 --file을 명시하는 방식도 유지합니다. --manifest를 생략하면 현재 디렉터리부터 상위에서 structly.yaml을 찾습니다.
• 계획의 changes는 지원 변경이며 current는 원문 정규형, new는 Catalog 값입니다. unsupported는 원문에서 직접 수정할 차이입니다. 라우트·요청·응답·operation 생성·삭제, OAS 3.0의 info.summary, 변수가 있는 servers와 공유 참조·별칭의 변경은 자동 반영하지 않습니다.
• --approve는 쉼표로 나눈 변경 ID를 받습니다. --approve-all은 같은 계획 토큰의 지원 변경만 승인하며 재조회 토큰이 다르면 반영하지 않습니다.
• 원문과 manifest의 해시가 읽은 뒤 달라지면 원본을 교체하지 않고 결과를 각 .new 파일에 남긴 뒤 실패합니다. 기존 .new는 덮어쓰지 않습니다. 일반 파일만 받고 각각 임시 파일을 rename해 교체하므로 두 번째 파일 교체 실패 시 첫 번째 파일이 반영될 수 있습니다. 오류가 안내한 로컬 파일을 확인합니다.
• --dry-run은 HTTP·파일 변경 없이 요청 계획만 출력합니다. --input JSON 방식은 --file과 함께 쓰지 않으며 응답만 출력합니다. content를 생략하면 저장 원문으로 계산합니다.
• export 결과를 검토·저장한 뒤 import해 서버 저장 원문을 맞춥니다. 지원 필드를 모두 맞췄다면 그 필드의 import 차이는 사라집니다.

제공 Service 확정#

apis service get의 ETag로 set-service를 실행합니다. Web UI는 API 상세의 제공 Service를 사용합니다(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"'

--service와 --none 중 하나만 지정합니다. --none은 명시적 미연결이며 오래된 ETag는 412입니다.

인증 변경 승인#

api.security는 API의 인증 방식·공통 요구사항, op:<operationId>:security는 Endpoint의 개별 재정의입니다. security_impacts에서 영향받는 Endpoint와 적용 전후를 확인합니다. 새 정의가 필요한 재정의나 사용 중인 정의 제거는 함께 필요한 변경을 승인해야 합니다. 미승인 참조·수동 Endpoint·삭제 후보에 끊어진 참조를 남기는 조합은 거부합니다.

인증 export는 미지원 차이로 표시되며 원문에서 수정하거나 import 방향으로 확정합니다. 다른 지원 필드만 export하면 원문의 인증 선언은 보존됩니다. 실제 로그인·토큰 발급·인증 서버 호출은 수행하지 않습니다.