OpenAPI data model, parser, and validator by halotukozak · Pull Request #2 · AVSystem/justworks

halotukozak · 2026-03-11T13:05:44Z

Summary

Intermediate data model (ApiSpec, TypeRef, SchemaModel, EnumModel) for parsed OpenAPI 3.0 specs
SpecParser — schemas, endpoints, oneOf/anyOf/allOf, discriminators, inline schemas, wrapper pattern detection
SpecValidator — checks for unsupported features (callbacks, links, etc.)
Test fixtures (petstore, polymorphic, anyOf, refs specs) and comprehensive tests

Test plan

./gradlew core:test passes (parser + validator tests)

Depends on #1

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 4.6 <[email protected]>

Intermediate model (ApiSpec, TypeRef, SchemaModel) for parsed OpenAPI specs. SpecParser handles schemas, endpoints, oneOf/anyOf/allOf, discriminators, inline schemas, and wrapper pattern detection. SpecValidator checks for unsupported features. Co-Authored-By: Claude Opus 4.6 <[email protected]>

Copilot

Pull request overview

This PR introduces an intermediate OpenAPI 3.0 data model plus a spec parser/validator implementation, along with test fixtures and unit tests to validate parsing behaviors (refs, anyOf/oneOf/allOf, discriminator handling, and Swagger 2.0 conversion). It also adds the Gradle wrapper/build configuration and CI workflow needed to run the test suite with coverage.

Changes:

Add ApiSpec/TypeRef-based intermediate model and SpecParser that transforms swagger-parser output into that model.
Add SpecValidator and a suite of parser/validator tests with multiple OpenAPI/Swagger fixtures.
Add Gradle wrapper/build configuration and a CI workflow to run tests with Kover coverage.

Reviewed changes

Copilot reviewed 23 out of 25 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
`settings.gradle.kts`	Defines root project name and includes `core` module.
`build.gradle.kts`	Sets up root Kotlin plugin version and common repositories/versioning.
`core/build.gradle.kts`	Adds core module deps (swagger-parser, kotlinpoet, datetime), test setup, publishing, and Kover.
`gradle.properties`	Enables Kotlin official code style.
`gradlew`	Adds Gradle wrapper POSIX script.
`gradlew.bat`	Adds Gradle wrapper Windows script.
`gradle/wrapper/gradle-wrapper.properties`	Pins Gradle distribution URL and wrapper settings.
`gradle/wrapper/gradle-wrapper.jar`	Adds Gradle wrapper JAR.
`.github/workflows/ci.yml`	CI job to run coverage task and upload report to Codecov on PRs.
`core/src/main/kotlin/com/avsystem/justworks/core/model/ApiSpec.kt`	Introduces intermediate API spec/domain model types (endpoints, schemas, enums, discriminator, etc.).
`core/src/main/kotlin/com/avsystem/justworks/core/model/TypeRef.kt`	Adds `TypeRef` sealed interface and `PrimitiveType` enum used by the parser/model.
`core/src/main/kotlin/com/avsystem/justworks/core/parser/ParseResult.kt`	Adds `ParseResult` for success/failure + warning propagation.
`core/src/main/kotlin/com/avsystem/justworks/core/parser/SpecParser.kt`	Implements OpenAPI parsing and transformation to the intermediate model (refs, inline schemas, combinators, etc.).
`core/src/main/kotlin/com/avsystem/justworks/core/parser/SpecValidator.kt`	Implements basic OpenAPI validation / unsupported feature checks.
`core/src/test/kotlin/com/avsystem/justworks/core/parser/SpecParserTest.kt`	Comprehensive parser tests (petstore, refs, invalid specs, Swagger v2 conversion, anyOf/mixed combinators, allOf property ref).
`core/src/test/kotlin/com/avsystem/justworks/core/parser/SpecParserPolymorphicTest.kt`	Tests polymorphic parsing behavior (allOf merge, oneOf refs, discriminator preservation).
`core/src/test/kotlin/com/avsystem/justworks/core/parser/SpecValidatorTest.kt`	Tests validator behavior for valid/missing-info specs.
`core/src/test/resources/petstore.yaml`	OpenAPI 3 petstore fixture used in parser tests.
`core/src/test/resources/petstore-v2.json`	Swagger 2.0 fixture used to test auto-conversion.
`core/src/test/resources/refs-spec.yaml`	Fixture to exercise `$ref` resolution in parameters and schema graphs.
`core/src/test/resources/polymorphic-spec.yaml`	Fixture to exercise oneOf/allOf + discriminator parsing.
`core/src/test/resources/anyof-spec.yaml`	Fixture for anyOf without discriminator.
`core/src/test/resources/anyof-valid-spec.yaml`	Fixture for anyOf with discriminator + mapping.
`core/src/test/resources/mixed-combinator-spec.yaml`	Fixture intended to fail when mixing oneOf+anyOf.
`core/src/test/resources/invalid-spec.yaml`	Fixture intended to fail validation (missing required `info`).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

core/src/main/kotlin/com/avsystem/justworks/core/parser/SpecParser.kt

core/src/main/kotlin/com/avsystem/justworks/core/parser/SpecValidator.kt

.github/workflows/ci.yml

core/src/main/kotlin/com/avsystem/justworks/core/parser/SpecParser.kt

# Conflicts: # .github/workflows/ci.yml

ktlint format

- Integrated Arrow core for improved null safety and functional error handling in `SpecParser` and `SpecValidator`. - Refactored validation logic to use Arrow's contextual `Raise` API, distinguishing errors and warnings as independent result types. - Added support for Kotlin compiler `-Xcontext-parameters` flag for cleaner contextual DSL usage. - Adjusted Gradle dependencies to include `arrow-core` and updated Kotlin compile configuration.

- Reorganized schema-handling logic to reduce duplication and enhance maintainability. - Simplified inline type reference creation and property extraction. - Improved handling of `oneOf`, `anyOf`, and `allOf` schemas with reusable utilities. - Replaced ad-hoc checks with clear helper functions for resolving primitives and composite types. - Optimized property and required field merging logic for `allOf` schemas, reducing redundancies.

…Arrow - Removed the `ParseResult` sealed interface and fully transitioned to Arrow's `Either` for handling parsing outcomes. - Refactored tests and internal methods to use `either` for improved safety and simplicity in error management. - Enhanced validation and schema parsing to seamlessly integrate with functional error handling.

Copilot

Pull request overview

Copilot reviewed 19 out of 20 changed files in this pull request and generated 10 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

core/src/main/kotlin/com/avsystem/justworks/core/parser/SpecParser.kt

core/src/test/kotlin/com/avsystem/justworks/core/parser/SpecParserTest.kt

core/src/test/kotlin/com/avsystem/justworks/core/parser/SpecParserPolymorphicTest.kt

core/src/main/kotlin/com/avsystem/justworks/core/parser/SpecValidator.kt

core/src/main/kotlin/com/avsystem/justworks/core/parser/SpecParser.kt

core/src/test/kotlin/com/avsystem/justworks/core/parser/SpecValidatorTest.kt

core/build.gradle.kts

core/src/main/kotlin/com/avsystem/justworks/core/parser/SpecParser.kt

- Set ktlint version to `1.8.0` as a temporary fix for known issue #912. - Removed unused imports and redundant helper functions from `SpecParser`. - Replaced custom string case conversion with `replaceFirstChar` for clarity and consistency.

…llOf - Remove Arrow either/Either usage from test helpers, use ParseResult pattern match - Fix SpecValidator test to use ValidationIssue.message - Fix null-safe allOf access in toTypeRef - Use resolveName() for identity-based schema resolution in toTypeRef Co-Authored-By: Claude Opus 4.6 <[email protected]>

Copilot

Pull request overview

Copilot reviewed 19 out of 20 changed files in this pull request and generated 5 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

core/src/main/kotlin/com/avsystem/justworks/core/parser/SpecParser.kt

core/build.gradle.kts

core/src/test/kotlin/com/avsystem/justworks/core/parser/SpecParserTest.kt

…extraction - Updated handling of `required` fields using `orEmpty

Group methods into logical sections: public API, transformation, endpoint/schema extraction, allOf merging, oneOf detection, type resolution, schema extensions, naming helpers, constants. Co-Authored-By: Claude Opus 4.6 <[email protected]>

Streamlined the code by removing section headers and redundant comments. Reformatted property extraction and type resolution logic for better readability.

- Removed redundant `SpecParser.` prefix in test assertions and parsing logic. - Updated tests for consistency and clarity in handling ParseResult types.

Copilot

Pull request overview

Copilot reviewed 19 out of 20 changed files in this pull request and generated 6 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

core/src/main/kotlin/com/avsystem/justworks/core/parser/SpecParser.kt

mzielu

Please take a look at copilot comments, they are valid

core/src/main/kotlin/com/avsystem/justworks/core/parser/SpecParser.kt

core/src/test/kotlin/com/avsystem/justworks/core/parser/SpecParserTest.kt

core/src/main/kotlin/com/avsystem/justworks/core/model/ApiSpec.kt

core/src/main/kotlin/com/avsystem/justworks/core/parser/SpecParser.kt

- Add KDoc to ParseResult sealed interface explaining Success/Failure pattern and .merge() usage - Add KDoc to SpecParser.parse() explaining params, return type, and Arrow either pattern - Add KDoc to SpecValidator.validate() explaining accumulate pattern and return semantics - Add explicit return type List<ValidationIssue> to SpecValidator.validate() - Remove unused imports from SpecValidator.kt (NonEmptyList, Raise, RaiseAccumulate, ensure, ensureNotNull, recover) - Add KDoc to ApiSpec data class explaining its role as intermediate model

- Add // -- Category -- grouping headers to SpecValidatorTest - Add missing test case: OpenAPI with no paths produces warning - Add assertIs import to support type-checking in the new test

Copilot

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 9 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

core/src/main/kotlin/com/avsystem/justworks/core/parser/SpecParser.kt

core/build.gradle.kts

core/src/test/kotlin/com/avsystem/justworks/core/parser/SpecParserTest.kt

core/src/main/kotlin/com/avsystem/justworks/core/parser/SpecParser.kt

…n `SpecParser` - Removed redundant `isEnum` property from `ApiSpec`. - Refined `allOf` property merging by adding parent context in `extractAllOfProperties`. - Standardized handling of `JSON_CONTENT_TYPE` and improved `oneOf` schema validation. - Fixed property ordering in operations and updated array/item resolution logic. - Adjusted compiler options configuration in Gradle for clarity and correctness.

- Replace `mapValuesNotNull` with stricter `associate` for clearer logic. - Enhance handling of `additionalProperties` in `toTypeRef`, supporting schema references and boolean validation. - Add fallback for unknown type handling in `toTypeRef`.

…extraction - Introduced `HttpMethod.parse` with case-insensitive parsing. - Updated `extractEndpoints` to leverage `HttpMethod.parse` for improved safety. - Refactored schema extraction logic to prevent redundancy and ensure unique definitions.

- Extract shared test logic into `SpecParserTestBase`. - Remove unused `loadResource` and `parseSpec` methods. - Clean up legacy validation logic in SpecParser tests. - Comment placeholder for future cookie parameter addition in `ParameterLocation`.

- Corrected the order of `extractEnumModel` and `extractSchemaModel` to ensure proper model generation.

Copilot

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 8 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

core/src/main/kotlin/com/avsystem/justworks/core/parser/SpecParser.kt

core/src/test/kotlin/com/avsystem/justworks/core/parser/SpecParserTest.kt

core/src/test/kotlin/com/avsystem/justworks/core/parser/SpecParserPolymorphicTest.kt

core/src/main/kotlin/com/avsystem/justworks/core/parser/SpecParser.kt

Co-Authored-By: Claude Opus 4.6 <[email protected]>

Copilot

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

core/src/main/kotlin/com/avsystem/justworks/core/parser/SpecParser.kt

…Parser - Simplified schema folding logic by using `toMap` for more concise and efficient transformation.

halotukozak and others added 2 commits March 11, 2026 14:02

feat: add Gradle build configuration with core module and CI

7cab983

Co-Authored-By: Claude Opus 4.6 <[email protected]>

Copilot AI review requested due to automatic review settings March 11, 2026 13:05

Copilot started reviewing on behalf of halotukozak March 11, 2026 13:06 View session

halotukozak changed the base branch from master to feat/gradle-plugin March 11, 2026 13:08

Copilot AI reviewed Mar 11, 2026

View reviewed changes

Merge branch 'feat/gradle-plugin' into feat/model-parser

ddfe68f

# Conflicts: # .github/workflows/ci.yml

Base automatically changed from feat/gradle-plugin to master March 11, 2026 13:35

halotukozak added 5 commits March 11, 2026 14:44

Merge branch 'feat/ktlint' into feat/model-parser

9e75f7a

chore: update Gradle properties and adjust ktlint rules

fb05a75

ktlint format

Copilot AI review requested due to automatic review settings March 11, 2026 19:07

Copilot started reviewing on behalf of halotukozak March 11, 2026 19:07 View session

Copilot AI reviewed Mar 11, 2026

View reviewed changes

halotukozak and others added 2 commits March 11, 2026 20:14

Copilot AI review requested due to automatic review settings March 11, 2026 19:30

Copilot started reviewing on behalf of halotukozak March 11, 2026 19:31 View session

Copilot AI reviewed Mar 11, 2026

View reviewed changes

halotukozak and others added 3 commits March 11, 2026 20:40

refactor: improve null-safe schema handling and consolidate property …

2ba35ba

…extraction - Updated handling of `required` fields using `orEmpty

refactor: remove redundant comments and improve SpecParser formatting

27d5d52

Streamlined the code by removing section headers and redundant comments. Reformatted property extraction and type resolution logic for better readability.

Copilot AI review requested due to automatic review settings March 11, 2026 19:44

Copilot started reviewing on behalf of halotukozak March 11, 2026 19:44 View session

refactor: simplify test cases by using direct ParseResult references

821834f

- Removed redundant `SpecParser.` prefix in test assertions and parsing logic. - Updated tests for consistency and clarity in handling ParseResult types.

halotukozak self-assigned this Mar 11, 2026

halotukozak requested a review from mzielu March 11, 2026 19:45

halotukozak mentioned this pull request Mar 11, 2026

Code generators (model, client, response, serializers) #4

Open

1 task

Copilot AI reviewed Mar 11, 2026

View reviewed changes

mzielu requested changes Mar 12, 2026

View reviewed changes

halotukozak added 2 commits March 12, 2026 16:22

refactor(01-01): verify and clean up parser test conventions

b79f705

- Add // -- Category -- grouping headers to SpecValidatorTest - Add missing test case: OpenAPI with no paths produces warning - Add assertIs import to support type-checking in the new test

Copilot AI review requested due to automatic review settings March 12, 2026 15:38

halotukozak force-pushed the feat/model-parser branch from a8a991e to b79f705 Compare March 12, 2026 15:38

Copilot started reviewing on behalf of halotukozak March 12, 2026 15:38 View session

Copilot AI reviewed Mar 12, 2026

View reviewed changes

halotukozak added 4 commits March 12, 2026 17:02

Copilot AI review requested due to automatic review settings March 13, 2026 11:05

Copilot started reviewing on behalf of halotukozak March 13, 2026 11:05 View session

refactor: fix enum and schema model extraction order in SpecParser

4b3063e

- Corrected the order of `extractEnumModel` and `extractSchemaModel` to ensure proper model generation.

Copilot AI reviewed Mar 13, 2026

View reviewed changes

halotukozak and others added 2 commits March 13, 2026 12:18

test: remove redundant blank line in SpecParserPolymorphicTest

dfc9dda

fix: add missing SpecParserTestBase extracted in previous refactor

7a2bd0d

Co-Authored-By: Claude Opus 4.6 <[email protected]>

Copilot AI review requested due to automatic review settings March 13, 2026 11:25

Copilot started reviewing on behalf of halotukozak March 13, 2026 11:25 View session

Copilot AI reviewed Mar 13, 2026

View reviewed changes

core/src/main/kotlin/com/avsystem/justworks/core/parser/SpecParser.kt Show resolved Hide resolved

core/src/main/kotlin/com/avsystem/justworks/core/parser/SpecParser.kt Show resolved Hide resolved

core/src/main/kotlin/com/avsystem/justworks/core/parser/SpecParser.kt Show resolved Hide resolved

halotukozak requested a review from mzielu March 13, 2026 12:09

refactor: replace asSequence with toMap for schema processing in Spec…

6cfb44d

…Parser - Simplified schema folding logic by using `toMap` for more concise and efficient transformation.

Conversation

halotukozak commented Mar 11, 2026

Summary

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mzielu left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!