Use more descriptive struct name than T (formerly Swagger)

[grokify]

I just noticed that the Swagger struct was renamed to T in v0.61.0 / PR #351

Would it be possible to use a more descriptive name? Perhaps something like Specification?

T is documented here with the following description:

T is the root of an OpenAPI v3 document

https://pkg.go.dev/github.com/getkin/kin-openapi@v0.61.0/openapi3#T

It seems Specification would be easier to understand. Document would be ok but with less context. T seems more difficult to comprehend and unusual as no other public struct name uses a single letter.

[fenollp]

Hello there, thanks for raising concerns. If you feel like something is under documented I'm happy to oblige and/or review PRs.
I agree renaming a couple types is quick however I'm afraid that ship has sailed.

T seems more difficult to comprehend and unusual as no other public struct name uses a single letter.

I fail to see your points there. The std lib has plenty of single letter names.

Again, thanks for discussing. We can always better document things and I'll happily help with that.

[grokify]

Documentation is a good idea and it could clarify why T was chosen and what meaning it has. Although the documentation describes T as "T is the root of an OpenAPI v3 document", T does not seem to represent "OpenAPI" or "Document".

I did notice that testing.T is used in the tests. Was T chosen because testing.T is used?

While the standard library does have some single letter names, I don't think they are common, and there is some association of the letter chosen with its use. Examples for testing.T and testing.B are below.

In testing, T is described as a parameter for "Test" functions:

T is a type passed to Test functions to manage test state and support formatted test log

https://golang.org/pkg/testing/#T

The testing package also uses B for a parameter to "Benchmark" functions:

B is a type passed to Benchmark functions to manage benchmark timing and to specify the number of iterations to run.

https://golang.org/pkg/testing/#B

[grokify]

For those that find T hard to use, to use a more descriptive name, I use an alias such as the following now:

type Spec = openapi3.T

This way, I can refer to Spec in my code instead of openapi3.T.