README
¶
pkg/parser/openapi
변경이력
- 2026-04-28: 초기 작성
역할
이미 kin-openapi 로 로드된 *openapi3.T 문서에서 operationId 단위로 요청/응답 필드의 type / format / length / enum / required 제약을 추출한다. 별도로 yaml.v3 raw 파싱으로 LineIndex 를 만들어 각 필드 / operationId / path / schema property 의 줄 번호를 색인한다.
진입점
| 함수 | 시그니처 | 설명 |
|---|---|---|
ExtractRequestConstraints |
(doc *openapi3.T, idx *LineIndex) map[op]map[field]FieldConstraint |
operationId 별 requestBody 제약 추출 |
ExtractResponseConstraints |
(doc *openapi3.T, idx *LineIndex) map[op]map[field]FieldConstraint |
operationId 별 첫 2xx 응답 제약 추출 |
BuildLineIndex |
(path string) (*LineIndex, error) |
openapi.yaml 을 yaml.v3 로 재파싱해 LineIndex 구축 |
DeriveSuccessStatus |
(op *openapi3.Operation, method string) int |
HTTP method 관례에 따른 성공 2xx 응답 코드 선택 |
Declared2xx |
(op *openapi3.Operation) []string |
operation 의 2xx 응답 코드 집합 |
공개 구조체
| 타입 | 설명 |
|---|---|
FieldConstraint |
단일 OpenAPI schema property 제약 (Type / Format / MaxLength / MinLength / Enum / Required / Line) |
LineIndex |
OpenAPI 노드별 줄 번호 색인 (OperationLine / RequestFieldLine / ResponseFieldLine / SchemaLine / SchemaPropertyLine / PathLine) |
비고
- doc 이 이미 파싱된 상태이므로 본 패키지 자체는 에러를 발생시키지 않는다 (
(result, []Diagnostic)시그니처를 따르지 않는 예외). LineIndex의 모든 lookup 메서드는 nil receiver 안전.
Documentation
¶
Index ¶
- func Declared2xx(op *openapi3.Operation) map[int]bool
- func DeriveSuccessStatus(op *openapi3.Operation, method string) int
- func ExtractErrorDisplayField(doc *openapi3.T) string
- func ExtractNoBodyOps(doc *openapi3.T) map[string]bool
- func ExtractPathParamTypes(doc *openapi3.T) map[string]map[string]string
- func ExtractRequestConstraints(doc *openapi3.T, lines *LineIndex) map[string]map[string]FieldConstraint
- func ExtractResponseArrayItemFields(doc *openapi3.T) map[string]map[string]map[string]bool
- func ExtractResponseArrayItemTypes(doc *openapi3.T) map[string]map[string]map[string]string
- func ExtractResponseConstraints(doc *openapi3.T, lines *LineIndex) map[string]map[string]FieldConstraint
- func ExtractResponseFieldTypes(doc *openapi3.T) map[string]map[string]FieldTypeInfo
- type FieldConstraint
- type FieldTypeInfo
- type LineIndex
- func (l *LineIndex) OperationLine(opID string) int
- func (l *LineIndex) PathLine(path string) int
- func (l *LineIndex) RequestFieldLine(opID, field string) int
- func (l *LineIndex) ResponseFieldLine(opID, field string) int
- func (l *LineIndex) SchemaLine(name string) int
- func (l *LineIndex) SchemaPropertyLine(schema, prop string) int
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Declared2xx ¶
Declared2xx is the exported form of declared2xx for callers outside this package (e.g. the openapi_ssac validator that implements XOS-82). Returns a fresh map so callers may mutate it safely.
func DeriveSuccessStatus ¶
DeriveSuccessStatus returns the 2xx status code that the generated handler for op (served via method) should emit. Order of preference is method-conventional (see httpMethodSuccessOrder); if none of those are declared, fall back to the lowest declared 2xx code so unusual operations still produce runnable code. Returns 0 when op is nil or declares no 2xx response — callers should treat 0 as "generator cannot proceed" and surface a diagnostic (see XOS-80/81).
func ExtractErrorDisplayField ¶
ExtractErrorDisplayField derives the field a generated mutation onError handler reads from a thrown server ErrorResponse. It scans schemas whose name contains "Error" (the XOE-01 heuristic) and returns:
- "error" when a string property "error" exists (current ErrorResponse contract — matches XOE-01's targets),
- "message" when "error" is absent but a string "message" exists,
- "error" as the default when neither exists or no schema is present.
The default keeps the generated handler's primary read schema-aligned and guarantees a non-empty field name, so codegen never emits a broken `e?. ?? e?.message` expression even for a nil document.
func ExtractNoBodyOps ¶
ExtractNoBodyOps returns a set of operationIds whose operations have no requestBody defined. These operations produce void mutations in React (mutate() instead of mutate({})).
func ExtractPathParamTypes ¶
ExtractPathParamTypes returns a map of operationId → paramName → OpenAPI type (e.g. "integer", "string"). Only path parameters are included.
func ExtractRequestConstraints ¶
func ExtractRequestConstraints(doc *openapi3.T, lines *LineIndex) map[string]map[string]FieldConstraint
ExtractRequestConstraints returns field constraints for the request body of each operationId. When lines is non-nil, each FieldConstraint.Line is set to the line number where the requestBody property is declared.
func ExtractResponseArrayItemFields ¶
ExtractResponseArrayItemFields returns a map of operationId -> array field name -> set of item property names. This is used to determine whether list items have an "id" field for React key assignment.
func ExtractResponseArrayItemTypes ¶
ExtractResponseArrayItemTypes returns a map of operationId → array field name → item property name → OpenAPI type (e.g. "integer", "string"). The react emitter consults it for row actions inside data-each: an item.<Field> mutate argument bound to an integer path parameter is wrapped with Number(...) only when the item field is not already a numeric type.
func ExtractResponseConstraints ¶
func ExtractResponseConstraints(doc *openapi3.T, lines *LineIndex) map[string]map[string]FieldConstraint
ExtractResponseConstraints returns field constraints for the 2xx response of each operationId. When lines is non-nil, each FieldConstraint.Line is set to the line number where the response schema property is declared.
func ExtractResponseFieldTypes ¶
func ExtractResponseFieldTypes(doc *openapi3.T) map[string]map[string]FieldTypeInfo
ExtractResponseFieldTypes returns a map of operationId → field path → FieldTypeInfo{Type, Format} from each operation's 2xx response schema. The keyed paths mirror the data-bind names the react emitter renders:
- top-level scalar/object properties (e.g. "can_delete", "summary")
- object dotted paths one level deep (e.g. "summary.credits_balance")
- array item properties (e.g. "photos.url")
Unlike ResponseArrayItemTypes (which carries only item field types for the Number() wrap of row-action arguments), this map covers the full bind surface and includes Format so the emitter can branch on date/date-time (plans/gen/frontend Phase037, BUG-126). allOf members are resolved one level deep, matching the validate-side responseFields judgment.
Types ¶
type FieldConstraint ¶
type FieldConstraint struct {
Type string
Format string
MaxLength *int
MinLength *int
Minimum *float64
Maximum *float64
Pattern string
Enum []string
Required bool
// ItemType: array 타입일 때 items 의 타입 (e.g., "string", "integer").
// 비-array 이면 빈 문자열.
ItemType string
// MapValueType: object(맵) 타입일 때 additionalProperties 의 값 타입
// (e.g., "string", "integer"). additionalProperties 가 자유형 object
// (스키마 없이 true, 또는 미지정) 이면 "*" 마커. 비-object 이면 빈 문자열.
MapValueType string
// Line: 해당 property 가 선언된 줄 번호 (1-based, 0 = 미상).
// LineIndex 와 매칭되어 채워지며, 검증 진단의 file:line 정확성 확보용.
Line int
}
FieldConstraint holds constraints for a single OpenAPI schema property.
type FieldTypeInfo ¶
type FieldTypeInfo struct {
Type string // OpenAPI type, e.g. "string", "integer", "boolean", "object", "array"
Format string // OpenAPI format, e.g. "date", "date-time", "uri" ("" when absent)
}
FieldTypeInfo carries the OpenAPI type and format of a response schema field. The react emitter consults it for type-aware data-bind rendering: the Type drives the boolean/number branch and Format ("date"/"date-time") drives the locale-formatting branch (plans/gen/frontend Phase037, BUG-126).
type LineIndex ¶
type LineIndex struct {
File string
// Operations: operationId → line of that operation block (the line where
// the operationId key appears). Indexed by operationId, not by path/method.
Operations map[string]int
// OperationFields: operationId → field name → line.
// Line where each property under
// requestBody.content.application/json.schema.properties is declared.
RequestFields map[string]map[string]int
// ResponseFields: operationId → field name → line.
// First 2xx response.content.application/json.schema.properties.
ResponseFields map[string]map[string]int
// Schemas: schema name → line of the schema block under components.schemas.
Schemas map[string]int
// SchemaProperties: schema name → property name → line.
SchemaProperties map[string]map[string]int
// Paths: path template → line of the path key (e.g. "/users/{id}").
Paths map[string]int
}
LineIndex maps OpenAPI nodes to their 1-based line numbers in the source YAML file. Because kin-openapi/openapi3 does not expose line information, the same file is parsed a second time with yaml.v3 to build this index.
All line numbers reference the line where the node's *key* appears (1-based). 0 means unknown.
func BuildLineIndex ¶
BuildLineIndex parses the given openapi.yaml with yaml.v3 in node mode and returns a LineIndex. Errors are non-fatal: a partially populated index is still returned (any field may be empty). 호출자는 line 0 을 "미상" 으로 간주.
func (*LineIndex) OperationLine ¶
OperationLine returns the line for the given operationId, or 0 if unknown.
func (*LineIndex) PathLine ¶
PathLine returns the line for a path key under paths:, or 0 if unknown.
func (*LineIndex) RequestFieldLine ¶
RequestFieldLine returns the line for a request body property of the given operationId, or 0 if unknown.
func (*LineIndex) ResponseFieldLine ¶
ResponseFieldLine returns the line for a response body property of the given operationId, or 0 if unknown.
func (*LineIndex) SchemaLine ¶
SchemaLine returns the line for a components.schemas entry, or 0 if unknown.
func (*LineIndex) SchemaPropertyLine ¶
SchemaPropertyLine returns the line for a schema property, or 0 if unknown.
Source Files
¶
- add_child_field_types.go
- add_field_types.go
- add_nested_field_types.go
- build_field_constraint.go
- build_line_index.go
- collect_field_types.go
- collect_item_field_types.go
- collect_item_fields.go
- collect_path_param_types_for_op.go
- collect_property_lines.go
- collect_request_constraints_for_op.go
- collect_response_array_item_fields_for_op.go
- collect_response_array_item_types_for_op.go
- collect_response_constraints_for_op.go
- collect_response_field_types_for_op.go
- declared_2xx.go
- declared_2xx_exported.go
- derive_success_status.go
- enum_to_strings.go
- extract_array_item_fields.go
- extract_array_item_types.go
- extract_body_constraints.go
- extract_error_display_field.go
- extract_no_body_ops.go
- extract_path_param_types.go
- extract_request_constraints.go
- extract_request_constraints_ops.go
- extract_response_array_item_fields.go
- extract_response_array_item_types.go
- extract_response_constraints.go
- extract_response_constraints_ops.go
- extract_response_field_types.go
- extract_response_fields.go
- extract_schema_constraints.go
- field_constraint.go
- field_type_info_of.go
- fill_request_field_lines.go
- fill_response_field_lines.go
- has_string_property.go
- http_method_success_order.go
- http_methods.go
- index_first_2xx_response.go
- index_operation.go
- index_path_item.go
- index_request_body.go
- index_schema_entry.go
- line_index.go
- line_index_operation_line.go
- line_index_path_line.go
- line_index_request_field_line.go
- line_index_response_field_line.go
- line_index_schema_line.go
- line_index_schema_property_line.go
- map_key.go
- map_value.go
- map_value_type.go
- schema_props_of_body.go
- type_field_type_info.go
- walk_components.go
- walk_paths.go
- walk_schemas.go