FDN-4939: Add OpenAPI 3.x import support#970
Open
jackl wants to merge 13 commits into
Open
Conversation
Implement OpenAPI 3.x import functionality following the existing Swagger 2.0 pattern. The new openapi module provides:
- Schema classification and conversion pipeline
- Type mapping from OpenAPI schema types to apibuilder scalar types
- Path/operation/parameter conversion
- Security scheme handling
- Full test coverage with FedEx OpenAPI specs
Uses OriginalType.UNDEFINED("open_api_3") for import detection.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
jackl
changed the title
… coverage - Narrow broad Exception catch in namespace inference to IllegalArgumentException - Replace unsafe .get calls with sys.error in ConverterMain - refName warns and returns raw string for non-standard $ref formats - resolveReference returns Either[String,String] instead of throwing on cycles - Warn when fields are dropped due to unresolved type (kind=None) - Warn at each array item type string fallback - Record issue when path has no typed response and is excluded from resources - Warn when requestBody $ref cannot be resolved - Wrap Converter.convert in Try in OpenApiServiceValidator for defence-in-depth - Wrap fromYaml/fromJson errors with JSON/YAML context prefix - Include exception class name in fromFile/fromUrl error messages - Add PathConverterSpec, SchemaResolverSpec, ConverterMainSpec, OpenApiParserSpec - Expand SchemaConverterSpec with SchemaConverter.convert output assertions - Expand ConverterSpec: assert resources non-empty, specific model names, filterHeaders e2e - Add NamingUtils edge cases and ApibuilderPrimitiveTypes membership tests Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…rage - classifyField now unwraps oneOf/anyOf nullable primitives: filters out the null member and classifies the remaining single primitive, fixing ~200 previously unmapped fields that used the oneOf+null pattern - Extend FormatMap with unixtime (→ long), uri/binary/byte/password/email (→ string), eliminating ~126 spurious ignored-format report entries Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds int8/int16/int32, uint8/uint16/uint32/uint64, double-int, decimal128, date-time-local, http-date, duration, uri-reference, uri-template, iri, iri-reference, idn-email, hostname, idn-hostname, base64url, sf-binary, html, commonmark, media-range, json-pointer, relative-json-pointer, regex, and char. Includes a link to the registry as the authoritative source. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Previously, each non-JSON content type generated a separate warning line, and warnings fired even when a JSON alternative existed for the same operation. Now: - Only warn when no application/json alternative is present (if JSON is available it is used and other types are silently ignored) - Consolidate all non-JSON types into one message per response/body - Format response keys as plain codes (200, default, 3xx) not case-class names Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
When a request body has no application/json content but the form content type carries a $ref schema, use that schema as the body type. This recovers the body type for file-upload and form-submission endpoints that define a named request model. The non-JSON body warning is also suppressed when a schema ref is successfully extracted. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds briefSummary to ConversionReport and writes it into the service description alongside the original OpenAPI description. Also emits an openapi_conversion attribute with per-category issue lists for tooling to consume. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Both types now produce an Authorization: Bearer header (matching the http/bearer treatment) rather than being skipped. The header description includes OAuth2 flow details (flow type, tokenUrl, scopes) or the OpenID Connect discovery URL so the information is not silently lost. A degraded note is emitted into the openapi_conversion attribute for each partially-converted scheme. Per-operation security warnings in PathConverter are suppressed when all referenced scheme names are convertible, and only fire for genuinely unconvertible schemes. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
oauth2 schemes now carry an 'oauth2' attribute with the full flows object (authorization/token URLs, refresh URL, scopes per flow). openIdConnect schemes carry an 'openid_connect' attribute with the discovery URL. This makes the security metadata machine-readable in the apibuilder output rather than only visible in the description text. Degraded notes updated to reference the attribute rather than saying the data is not representable. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Jira: https://flowio.atlassian.net/browse/FDN-4416
Adds OpenAPI 3.x import support to apibuilder following the same pattern as the existing Swagger 2.0 module.
openapisbt module with a full schema classification and conversion pipeline (objects, enums, arrays, unions, aliases, maps, security schemes, paths/operations/parameters/responses)OriginalUtil.guessType, dispatching toOpenApiServiceValidatorviaOriginalType.UNDEFINED("open_api_3")ConverterMainCLI for developer testing — run directly from sbt while iterating on conversions:Dependencies
com.github.apicollective:apibuilder-validation:0.5.8via JitPack (Scala 3 artifact published without version suffix — uses single%)com.softwaremill.sttp.apispec0.11.10 for the OpenAPI modelTest plan
sbt "openapi/test"→ all passNotes
OriginalType.UNDEFINED("open_api_3")to avoid a blocking API spec change; a follow-up ticket should add a properOriginalType.OpenApi3valuePathConverterSpecEng-Review Summary
Title: PathConverter lacks dedicated unit tests
Location: no PathConverterSpec
Resolution: justified
Justification: Covered indirectly via FedEx integration tests in ConverterSpec; unit spec to follow in a subsequent PR