API 문서: OpenAPI, Swagger, Postman

TL; DR

OpenAPI-진실의 원천: 계약 → SDK → 모키 → 테스트 → 포털.
Swagger UI/Redoc-읽을 수있는 쇼케이스; Postman - 실행 가능한 스크립트.
우리는 라인터, 브레이크 체크, 예 및 오류 체계를 꿰매고 SDK 및 Mock 서버를 생성하며 버전이있는 개발 포털 및 "일몰" 을 게시합니다.

1) 목표와 원칙

계약 1 (OpenAPI). 다른 모든 것이 생성됩니다.
문서는 실행 가능합니다. 샘플 요청은 Postman/CLI에서 테스트됩니다.
기본 보안: 오류 체계, 제한, 인증.
검증 및 수명주기: 'v1 '/' v2', 우울증/일몰, 변경 로그.

2) OpenAPI 구조 (최소 골격)

yaml openapi: 3. 0. 3 info:
title: Payments API version: 1. 2. 0 description: >
Payment transactions: auth/capture/refund/payout. All responses contain trace_id.
servers:
- url: https://api. example. com/v1 tags:
- name: Payments
- name: Payouts components:
securitySchemes:
oauth2:
type: oauth2 flows:
clientCredentials:
tokenUrl: https://idp. example. com/oauth/token scopes:
payments: read: read payments: write: write payments schemas:
Error:
type: object required: [error, error_description, trace_id]
properties:
error: { type: string }
error_description: { type: string }
trace_id: { type: string, format: uuid }
security:
- oauth2: [payments:read]
paths:
/payments/{id}:
get:
summary: Receive payment tags: [Payments]
parameters:
- in: path name: id required: true schema: { type: string, format: uuid }
responses:
'200':
description: Content succeeded:
application/json:
schema: { $ref: '#/components/schemas/Payment' }
'404': { $ref: '#/components/responses/NotFound' }
components:
responses:
NotFound:
description: Content not found:
application/json:
schema: { $ref: '#/components/schemas/Error' }

• 스키마/응답/매개 변수/요청자를 '구성 요소' 로 분해하십시오.
• SecuritySchemes (OAuth2/JWT/HMAC) 를 설명하고 '경로 '/' 글로벌' 수준에서 적용하십시오.

3) 오류 표준 및 메타 데이터

yaml components:
schemas:
ApiError:
type: object required: [error, error_description, trace_id]
properties:
error: { enum: [invalid_request, not_found, rate_limited, internal] }
error_description: { type: string }
trace_id: { type: string, format: uuid }

항상 429 (속도 제한), 401/403 및 헤더 'X-RateLimit-', 'Redue-After' 를 문서화하십시오.

4) 예: 요청/응답, 컬 및 SDK

각 종점에 대해: 최소 및 확장 된 예.
OpenAPI에서 컬 및 코드 스 니펫 (JS/파이썬/Go) 을 생성합니다. 손으로 쓰지 마십시오.

실제 값 적용하기: UUI, ISO 날짜, "사소한" (센트) 합계

yaml examples:
ok:
value:
id: "pay_123"
amount_minor: 1099 currency: "EUR"
status: "captured"
created_at: "2025-11-03T12:34:56Z"

5) Swagger UI/Redoc-게시 방법

1. Swagger UI (인터랙티브, 트라이 아웃),

2. Redoc (긴 페이지 읽기).

포함: 어두운 테마, 검색, 버전 선택기 ('v1', 'v2'), 우울증 배너.

생산 영역에 대해 "시도" 를 숨기고 샌드 박스에 허용하십시오.

6) 우편 배달부 컬렉션: 라이브 스크립트

OpenAPI에서 컬렉션을 자동화하고 환경 변수 ('{{baseUrl}', '{{accessToken}}') 를 지원합니다.
사전 테스트 (토큰 획득) 및 사후 테스트 (주장 상태/스키마) 를 추가하십시오.
폴더로 나누기: Auth, Payments, Payouts, Webhooks.
중요한 경로에 대한 수출 모니터 (예약).

js pm. test("status is 200", () => pm. response. code === 200);
pm. test("schema valid", () => tv4. validate(pm. response. json(), pm. collectionVariables. get("schema_payment")));

7) 모키와 샌드 박스

OpenAPI에서 모의 서버를 생성합니다 (예/' 예 '/' 예 ').
mocs의 한계: demempotency, 지연, 랜덤 오류 (UAT의 경우) 를 나타냅니다.
문서 샌드 박스 대 prod 차이 (제한, 데이터, 지연).

8) SDK 자동 생성

OpenAPI에서 공식 SDK (TypeScript, Python, Go) 를 생성하십시오.
SDK 릴리스 정책 = SemVer, API 버전 매핑.
README SDK: 인증, retray, demempotency, 429/Readed-After 처리.

9) 연결, 파손 점검 및 CI

라이터: 스펙트럼 (스타일/안티 패턴), openapi-diff (브레이킹 체크).

• 회로 유효성 검사기,
• 린터,
• ioc 서버에 대한 계약 테스트
• Swagger/Redoc/collection 어셈블리,
• 포털에 게시 (staging → prod),
• 우울증/일몰 경고.

10) 검증, 우울증, 일몰

(PHP 3 = 3.0.6, PHP 4) 버전 '.
비난 플래그: 'Deprecation: 참', '일몰: <RFC1123 날짜>', '링크: <changelog>' 헤더.
포털에서 - 분리 전 배너 및 타이머; v1에 대한 Postman 컬렉션이 동결되었습니다 (버그 수정 만).

11) 부두의 보안 및 개인 정보 보호

비밀, 내부 탭, 실제 PAN/PII를 게시하지 마십시오.
민감한 필드의 경우-마스킹 및 스터브 예.
Swagger "Try it out" → 속도 제한이있는 샌드 박스에만 적용됩니다.
OAuth2/OIDC, HMAC (웹 후크 용) 및 mTLS (필요한 경우) 를 명확하게 설명합니다.

12) 스타일 가이드 계약

복수 자원: '/payment ', '/payouts'.
식별자: 'pay _', 'po _', UUIDv4 또는 ksuid.
날짜-UTC ISO-8601; 돈- 'm액 _ minor + 통화'.
페이지 기반 - 커서 기반 ('? 커서 = & limited = '), 안정적인 정렬.
Idempotency- 돌연변이를위한 'Idempotency-Key'.
목록에 대한 안정적인 객체 'meta' 및 'links'.

13) 부두의 "웹 후크" 섹션

이벤트 봉투, HMAC 서명, 시간 창, 배상, 응답 코드가있는 별도의 섹션.
로컬 서명 확인을위한 이벤트 본문 및 Postman 컬렉션 샘플.
재생/DLQ 엔드 포인트 및 UAT 체크리스트.

14) 데브 포털: 역할 및 출판

섹션: 개요, 시작, 인증, 엔드 포인트, 예, 웹 후크, SDK, 제한, Changelog.
역할: Steward API (표준), Domain Owner (컨텐츠), Tech Writer (편집), DevRel (포털/커뮤니티).
기능: 스키마 필드를 통한 검색, 샘플 복사, "수집 요청" → Postman.

15) 점검표

• OpenAPI가 유효합니다. 오류없이 린터.
• 예는 200/4xx/429/5xx를 포함합니다.
• 보안: 설명 된 체계, 비밀 없음.
• Swagger/Redoc 및 Postman (prod/sandbox) 을 형성했습니다.
• SDK가 생성 및 게시되었습니다.
• 변경 로그 및 버전 선택기가 업데이트되었습니다

• 우울증/일몰 헤더가 포함되어 있습니다.
• 포털의 배너, 파트너에게 보내는 편지.
• 레거시 통화 메트릭이 대상으로 떨어집니다.

16) 반 패턴

진실의 중복 소스 (wiki 단위 OpenAPI).
Postman에서 달리지 않고 "눈으로" 의 예.
단일 오류 형식이 없습니다.
그림% 1개의 캡션을 편집했습니다.
음식에 접근 할 수 있고 제한이 없습니다.
일관되지 않은 페이지 매김 및 인증 체계.

17) 자동화의 미니 스 니펫

bash openapi2postmanv2 -s openapi. yaml -o postman. json -p

yaml steps:
- run: spectral lint openapi. yaml
- run: openapi-diff --fail-on-breaking main. yaml openapi. yaml
- run: redoc-cli bundle openapi. yaml -o site/redoc. html
- run: swagger-cli bundle openapi. yaml -o site/swagger. json
- run: openapi2postmanv2 -s openapi. yaml -o site/postman. json -p
- run: npm run deploy:portal

18) 현지화 및 가용성

개별 정보. 설명 _ <lang> '또는 두 개의 포털 어셈블리 (EN/RU).
용어집 용어 (KYC/AML, 지불, demempotency).
대조, 키보드 탐색, 어두운 테마.

요약

문서 파이프 라인 조립: 단일 OpenAPI 계약 → 라인터 및 중단 확인 → Swagger/Redoc 쇼케이스 → Postman 컬렉션 및 모의 서버 → SDK → 버전 포털 및 일몰. 일반적인 예, 단일 오류 형식 및 강력한 인증은 선반의 PDF에서 작업 통합 도구로 문서를 변환하여 파트너 속도를 높이고 지원 비용을 줄입니다.