I've gathered the feedback received so far in the pitch and discussion threads in order to collect my thoughts a bit more. Thanks to everyone who has had input.
I'd ask the following of anyone with time for it: Please read the brief summary below and let me know if you have any feedback not captured so far.
Dictionary Ordering
From OpenAPIKit - #2 by lassejansen
Feedback
OpenAPIKit did not preserve dictionary ordering when decoding/encoding. This caused semantic problems where ordering of OpenAPI components was deliberate and it separately caused problems for diffing algorithms that might pick up on ordering differences even though no intentional changes were made.
Resolution
OpenAPIKit began using an OrderedDictionary
type in version v0.13.0. This means that if the Encoder and Decoder being used support stable ordering (some do and some don't) then OpenAPIKit will retain that ordering.
Compatibility Testing
From OpenAPIKit - #4 by mackoj
Feedback
OpenAPIKit did not test itself against any publicly available OpenAPI documentation.
Resolution
OpenAPIKit gained a compatibility test suite in v0.19.0. The suite only contains two different APIs so far, but it has already proven useful in catching edge cases not previously dreamt up in any unit tests. More APIs will be added in the future.
Error Handling
From OpenAPIKit - #2 by lassejansen
Feedback
OpenAPIKit did not provide concise understandable parsing errors.
Resolution
This was largely addressed by v0.21.0 which introduced a series of error types and one wrapper type called OpenAPI.Error
that together offer up vastly improved error descriptions.
Reflection (via Mirror)
From OpenAPIKit - #12 by tanner0101
Feedback
There are a likely a lot of opinions on how to go about supporting OpenAPI generation via reflection. This could be moved to its own package.
Resolution
As of OpenAPIKit v0.23.0, existing reflection support has moved into another library called OpenAPIReflection. The features and maturity of that library need not be tied to that of OpenAPIKit.
JSONReference
From [Discussion] OpenAPIKit - #2 by tanner0101
Feedback
JSONReference
code is difficult to understand.
Resolution
JSONReference
was reworked in OpenAPIKit v0.24.0 to simplify and document the code and to improve the public API at the same time.
Dependencies
From OpenAPIKit - #12 by tanner0101
Feedback
OpenAPIKit pulls in a lot of dependencies.
Resolution
Since version 0.26.0 OpenAPIKit has had no external dependencies other than those used exclusively in test targets.
Public API Audit
From [Discussion] OpenAPIKit - #2 by tanner0101
Feedback
OpenAPIKit could benefit from an audit of its public API to make sure things that could be private/internal are not unnecessarily exposed (and therefore maintained) as public API.
Resolution
Tracked as ticket #25. I intend to tackle this soon, and certainly prior to v1.0.0.
Code Standards
From [Discussion] OpenAPIKit - #2 by tanner0101
Feedback
There are unnecessary abbreviations in use in OpenAPIKit in breach of the coding standards.
Resolution
I audited the codebase for abbrevations both in public APIs and in internal code. I removed all unnecessary abbrevations I found.