Before we go further, let’s we see how the different between OAS 2.0 and OAS 3.0 on this documentation :
OAS 2.0: https://swagger.io/docs/specification/2-0/api-host-and-base-path/OAS 3.0: https://swagger.io/docs/specification/api-host-and-base-path/
Then, I found interesting discussion on reddit forum about generate open api 3.0 for Go:
Based on that, I found some disclosure below.
No Multiple BasePath version on OAS 2.0
Based on documentation swagger, there is no multiple basepath option on OAS 2.0.
Therefore when we use swagger generator for 2.0 in golang like:
We can’t use multiple base path in 2.0, so if we want to add multi-basepath:
- We could set to global path like “domain.com/swagger/index.html” and Read all basepath to set empty basepath. So we can see all version on our global swagger: /v1/service, /v2/service, /v3/service
- If we still want to multi-basepath with different swagger docs, we should add another swagger docs in different version of .json, .yaml, docs.go. Maybe like swaggerV1.go, swaggerV2.go, swaggerV3.go.
Still in research generator OAS 3.0 for Go
I found some library that research generator for OAS 3.0 in Go:
- https://github.com/deepmap/oapi-codegen (this one is relevant)
- https://github.com/OpenAPITools/openapi-generator
- https://github.com/getkin/kin-openapi
- https://github.com/go-openapi/spec3
- https://github.com/google/gnostic
Source: https://openapi.tools/
So I suggest to manually generate doc OAS 3.0, I still searching for stable library to generate swagger 3.0 in Go. If you know some, let’s comment below.
Conclusion
I have to still to use OAS 2.0 in Go today. Because I think it’s stable and supported SDKs to generate it.
I found some article that relevant with this:
- https://medium.com/easyread/mempercepat-proses-development-dengan-open-api-3-8502011b7463
- https://toolbox.kurio.co.id/levelling-up-api-documentation-7c26b37715bb
- https://levelup.gitconnected.com/tools-for-implementing-a-golang-api-server-with-auto-generated-code-and-documentation-694262e3866c
Thank You!
