openapi3: support format conditional on `doc.openapi` version by cboitel · Pull Request #744 · getkin/kin-openapi

cboitel · 2023-01-17T21:30:35Z

Implements string format improvements in issue #582 with openapi minor version support.

You can now define a string formats available for some minor version
by default, string formats apply to all minor versions (>= 3.0)
filters do enforce string formats according to document's OpenAPI version

cboitel · 2023-01-18T21:01:15Z

@fenollp finally made up with implementing a string format support based on OpenAPI minor version

fenollp

Hey! Thanks for this. This is going to the right direction. I mostly have comments on the API design.

fenollp · 2023-05-18T09:55:58Z

+func (format *Format) add(minMinorVersion uint64, vFormat *versionedFormat, override bool) {
+	if format != nil {
+		if format.versionedFormats == nil {
+			format.versionedFormats = make([]*versionedFormat, minMinorVersion+1)


This is allocating a lot of unused space. I'd rather you use a dynamically-sized map. Use an additional slice for ordered map keys.

Did that so it is very fast to determine format to use for a specific minor version when validating.

Since number of minor versions won't be too big, I don't think this can be an memory issue.

fenollp · 2023-05-18T09:58:41Z

+	return nil
+}
+
+func (format Format) DefinedForMinorVersion(minorVersion uint64) bool {


This seems unused.

Will have to determine if we keep it so one can determine if a definition already exists for a specific minor version. Since format does not expose its content, this is the only way for one to know about it.

If we keep, I will need to add tests

fenollp · 2023-05-18T10:13:12Z

+
+// DefineStringFormatStartingWithOpenAPIMinorVersion defines a new regexp pattern for a given format to apply for a minor version of OpenAPI 3
+// override allows to enforce regex usage to all subsequent minor versions of OpenAPI
+func DefineStringFormatStartingWithOpenAPIMinorVersion(name string, fromMinorVersion uint64, pattern string, override bool) {


Why uint64? uint8 or even uint16 is large enough.

I like the idea but I'd rather have a simpler API:

a shorter method such as the existing DefineStringFormat (extend with variadic args)

make override=true the only behavior. API users will simply make multiple calls to cut specific ranges

turn fromMinorVersion into a float (f32 if for all Y, 3.Y can be expressed and I believe it's a yes) so users can see DefineStringFormat(name, pattern, 3.1). The call should panic on non-nil non-floats and compare minors with a 0.4 epsilon.

(yes, I'm asking to extend the existing 2 methods with a variadic float)

uint64 comes from the string parsing function used when parsing OpenAPI document
=> Go string parsing returns a uint64
=> Casting to uint8 would require minor version

Since most processors are 64 bits, using an uint8/uint64 does save memory nor it brings performance gain.

Gone with the variadic options. have a look

fenollp · 2023-05-18T10:15:01Z

+func TestStringFormatsStartingWithOpenAPIMinorVersion(t *testing.T) {
+	DefineStringFormatStartingWithOpenAPIMinorVersion("test", 0, "test0", false)
+	for i := uint64(0); i < 10; i++ {
+		if assert.Contains(t, SchemaStringFormats, "test") &&


Please prefer the require package over assert. This makes for fewer nesting.

fenollp · 2023-05-18T10:16:48Z


 	customizeMessageError func(err *SchemaError) string
+
+	openapiMinorVersion uint64 // defaults to 0 (3.0.z)


uint8 is enough

see discussion earlier

fenollp · 2023-05-18T10:26:31Z

+}
+
+// MinorVersion returns minor version from string assuming 0 is the default
+func (oai Version) Minor() uint64 {


uint64 seems too big. Also why not return the two possible errors? (or edit func doc)

I see you introduced this for use by the schema validation settings. Let's return a float then :)

fenollp · 2023-05-18T10:32:48Z

 const FormatOfStringForUUIDOfRFC4122 = `^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$` ...
 const SerializationSimple = "simple" ...
 var SchemaErrorDetailsDisabled = false ...
+var ErrInvalidVersion ...


What's your rationale to export this?

So one can check at loading time he got an invalid error version, not some other kind of error.

fenollp · 2023-06-18T11:59:55Z

@cboitel Hey there. Do you need help moving this forward?

cboitel · 2023-06-18T12:21:31Z

Nope. Just missed it while I was on vacations. Will get back to it next week.

cboitel · 2023-07-30T16:35:31Z

@fenollp

I had a hard time to rebase.

Finally found it was related to some new/existing tests defining string formats for uuid but not restoring string formats to original value.

I created a new Save/Restore/RestoreDefault functions for string formats so one can easily do that like we need in our tests.

I will now address your earlier comments in the upcoming days.

…ilable

cboitel changed the title ~~582 enhance format support 2~~ #582 enhance format support Jan 17, 2023

github-advanced-security AI found potential problems Jan 17, 2023

View reviewed changes

Comment thread openapi3filter/validate_request.go Fixed

Comment thread openapi3filter/validate_request.go Fixed

Comment thread openapi3filter/validate_response.go Fixed

Comment thread openapi3filter/validate_response.go Fixed

cboitel force-pushed the 582-enhance-format-support-2 branch 2 times, most recently from 3301b24 to ab2416b Compare January 17, 2023 22:18

fenollp requested changes Jan 20, 2023

View reviewed changes

Comment thread openapi3/version_test.go

fenollp requested changes May 18, 2023

View reviewed changes

fenollp changed the title ~~#582 enhance format support~~ openapi3: support format conditional on doc.openapi version May 18, 2023

fenollp mentioned this pull request Jun 22, 2023

Which version of OpenAPI spec does Validate(context.Context, ...ValidationOption) method validate against? #812

Closed

cboitel force-pushed the 582-enhance-format-support-2 branch 2 times, most recently from 6855e99 to bb0e0e5 Compare July 30, 2023 16:23

cboitel force-pushed the 582-enhance-format-support-2 branch 2 times, most recently from eaa7245 to 0e202c6 Compare July 31, 2023 11:50

cboitel added 5 commits September 17, 2023 14:47

feat getkin#582: implement openapi version validation

96f4c5e

feat getkin#582: add minor version support to string formats

9c0054f

fix getkin#582: enhance date string formats

21c4aa6

fix getkin#582: define OpenAPI 3.1 string formats

bcbbb97

feat getkin#582: use OpenAPI minor version during validation when ava…

355d474

…ilable

cboitel force-pushed the 582-enhance-format-support-2 branch from 0e202c6 to 355d474 Compare September 17, 2023 12:48


		customizeMessageError func(err *SchemaError) string

		openapiMinorVersion uint64 // defaults to 0 (3.0.z)

Uh oh!

Conversation

cboitel commented Jan 17, 2023

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cboitel commented Jan 18, 2023

Uh oh!

Uh oh!

fenollp left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cboitel Jul 30, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

fenollp commented Jun 18, 2023

Uh oh!

cboitel commented Jun 18, 2023

Uh oh!

cboitel commented Jul 30, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

cboitel Jul 30, 2023 •

edited

Loading