56 lines
1.1 KiB
Markdown
56 lines
1.1 KiB
Markdown
# KBX v13 — API Field Contract
|
|
|
|
## 목표
|
|
|
|
Frontend의 `field="orderQty"`, Server Validation의 `field="orderQty"`, OpenAPI 문서의 Field 식별자를 동일하게 유지한다.
|
|
|
|
## C# Attribute
|
|
|
|
```csharp
|
|
[property: KbxFieldKey(KbxFieldKeys.OrderQty)] decimal? OrderQty
|
|
```
|
|
|
|
`KbxFieldOpenApiSchemaFilter`는 Swashbuckle Schema에 다음 vendor extension을 추가한다.
|
|
|
|
```text
|
|
x-kbx-field-key
|
|
x-kbx-field-label
|
|
x-kbx-sensitive
|
|
x-kbx-masking
|
|
```
|
|
|
|
등록 예:
|
|
|
|
```csharp
|
|
builder.Services.AddSwaggerGen(options =>
|
|
{
|
|
options.AddKbxFieldContract();
|
|
});
|
|
```
|
|
|
|
## 중요한 경계
|
|
|
|
OpenAPI extension은 구조/표시 계약을 제공한다.
|
|
다음은 OpenAPI Field Metadata로 생성하지 않는다.
|
|
|
|
- 업무 상태 전이
|
|
- 재고 가능 여부
|
|
- 권한 최종 판정
|
|
- 동시성 판정
|
|
- Domain invariant
|
|
|
|
## Validation Problem
|
|
|
|
Row 오류는 canonical key를 사용한다.
|
|
|
|
```json
|
|
{
|
|
"field": "orderQty",
|
|
"rowKey": "line-7",
|
|
"code": "QUANTITY_POSITIVE",
|
|
"message": "수량은 0보다 커야 합니다."
|
|
}
|
|
```
|
|
|
|
DB column이 `quantity`여도 사용자/API 오류 계약의 FieldKey는 `orderQty`를 사용한다.
|