Supprt OpenAPI Specification Version 3.0.2

[kshamiev]

Is your feature request related to a problem? Please describe.
Not support OAS version 3.0.2

Describe the solution you'd like
feature support OAS version 3.0.2

[pei0804]

Do you know good openapi v3 spec library for go ?

[chenjpu]

kin-openapi ,is it okay?

[betabandido]

It does not look like go-openapi will support openapi 3 any time soon. See:

go-openapi/spec#21
go-openapi/spec3#1

kin-openapi appears mentioned in the first issue as a good candidate to provide openapi 3 support. So, it might be a good idea to look into it.

Not supporting openapi 3 makes impossible to document APIs that could otherwise be documented with swag (e.g., when using QueryMap method in Gin).

[serg-kovalev]

Hi guys,
any updates?

[OneCricketeer]

I've worked around this with some Make targets

The first runs swag init on the root project, creating the docs/swagger.json and docs/swagger.yaml

The second mounts that folder and generates a v3 folder with openapi-generator-cli

docs
├── .openapi-generator-ignore
├── docs.go
├── swagger.json
├── swagger.yaml
└── v3
    ├── README.md
    ├── openapi.json
    └── openapi.yaml

Makefile

# Docker image to run shell and go utility functions in
WORKER_IMAGE = golang:1.15-alpine3.13
# Docker image to generate OAS3 specs
OAS3_GENERATOR_DOCKER_IMAGE = openapitools/openapi-generator-cli:latest-release

.PHONY: ci-swaggen2
ci-swaggen2:
	@docker run --rm -v $(PWD):/work $(WORKER_IMAGE) \
	  sh -c "apk update && apk add --no-cache git; go get -u github.com/swaggo/swag/cmd/swag && (cd /work; swag init)"

# Generate OAS3 from swaggo/swag output since that project doesn't support it
# TODO: Remove this if V3 spec is ever returned from that project
.PHONY: ci-swaggen
ci-swaggen: ci-swaggen2
	@echo "[OAS3] Converting Swagger 2-to-3 (yaml)"
	@docker run --rm -v $(PWD)/docs:/work $(OAS3_GENERATOR_DOCKER_IMAGE) \
	  generate -i /work/swagger.yaml -o /work/v3 -g openapi-yaml --minimal-update
	@docker run --rm -v $(PWD)/docs/v3:/work $(WORKER_IMAGE) \
	  sh -c "rm -rf /work/.openapi-generator"
	@echo "[OAS3] Copying openapi-generator-ignore (json)"
	@docker run --rm -v $(PWD)/docs/v3:/work $(WORKER_IMAGE) \
	  sh -c "cp -f /work/.openapi-generator-ignore /work/openapi"
	@echo "[OAS3] Converting Swagger 2-to-3 (json)"
	@docker run --rm -v $(PWD)/docs:/work $(OAS3_GENERATOR_DOCKER_IMAGE) \
	  generate -s -i /work/swagger.json -o /work/v3/openapi -g openapi --minimal-update
	@echo "[OAS3] Cleaning up generated files"
	@docker run --rm -v $(PWD)/docs/v3:/work $(WORKER_IMAGE) \
	  sh -c "mv -f /work/openapi/openapi.json /work ; mv -f /work/openapi/openapi.yaml /work ; rm -rf /work/openapi"

Run make ci-swaggen, and we've hooked into our CI pipeline on every commit to master

[lifegit]

I've worked around this with some Make targets

The first runs swag init on the root project, creating the docs/swagger.json and docs/swagger.yaml

The second mounts that folder and generates a v3 folder with openapi-generator-cli

docs
├── docs.go
├── swagger.json
├── swagger.yaml
└── v3
    ├── README.md
    ├── openapi.json
    └── openapi.yaml

# Docker image to run shell and go utility functions in
WORKER_IMAGE = golang:1.15-alpine3.13
# Docker image to generate OAS3 specs
OAS3_GENERATOR_DOCKER_IMAGE = openapitools/openapi-generator-cli:latest-release

.PHONY: ci-swaggen2
ci-swaggen2:
	@docker run --rm -v $(PWD):/work $(WORKER_IMAGE) \
	  sh -c "apk update && apk add --no-cache git; go get -u github.com/swaggo/swag/cmd/swag && (cd /work; swag init)"

# Generate OAS3 from swaggo/swag output since that project doesn't support it
# TODO: Remove this if V3 spec is ever returned from that project
.PHONY: ci-swaggen
ci-swaggen: ci-swaggen2
	@echo "[OAS3] Converting Swagger 2-to-3 (yaml)"
	@docker run --rm -v $(PWD)/docs:/work $(OAS3_GENERATOR_DOCKER_IMAGE) \
	  generate -i /work/swagger.yaml -o /work/v3 -g openapi-yaml --minimal-update
	@docker run --rm -v $(PWD)/docs/v3:/work $(WORKER_IMAGE) \
	  sh -c "rm -rf /work/.openapi-generator"
	@echo "[OAS3] Copying openapi-generator-ignore (json)"
	@docker run --rm -v $(PWD)/docs/v3:/work $(WORKER_IMAGE) \
	  sh -c "cp -f /work/.openapi-generator-ignore /work/openapi"
	@echo "[OAS3] Converting Swagger 2-to-3 (json)"
	@docker run --rm -v $(PWD)/docs:/work $(OAS3_GENERATOR_DOCKER_IMAGE) \
	  generate -s -i /work/swagger.json -o /work/v3/openapi -g openapi --minimal-update
	@echo "[OAS3] Cleaning up generated files"
	@docker run --rm -v $(PWD)/docs/v3:/work $(WORKER_IMAGE) \
	  sh -c "mv -f /work/openapi/openapi.json /work ; mv -f /work/openapi/openapi.yaml /work ; rm -rf /work/openapi"

Runs with make ci-swaggen, and is hooked into our CI pipeline on every commit to master

Excuse me, I don't understand how to use it, would you like to help me ?

[OneCricketeer]

@lifegit Create a Makefile with that content, and run the command I mentioned

[lifegit]

@OneCricketeer
thank you very much ! I've run it successfully.

[hotrungnhan]

uppppppppppppppppppp

[hotrungnhan]

how about this lib https://github.com/getkin/kin-openapi

[OneCricketeer]

@hotrungnhan What about it? It was already mentioned in the third comment

[hotrungnhan]

@hotrungnhan What about it? It was already mentioned in the third comment

oh im sorry i did't read thi third comment.

[thetruechar]

Any update?

[s4l1h]

The easiest way is using the swagger editor. You just need to import your swagger.json file and convert to openapi 3.
https://editor.swagger.io/

source: https://stackoverflow.com/a/59749691

[kolaente]

The easiest way is using the swagger editor. You just need to import your swagger.json file and convert to openapi 3.
https://editor.swagger.io/

How can I automate that to automatically publish an up to date swagger spec with every nighly build of my software?

[RStahanFX]

https://converter.swagger.io/#/Converter/convertByContent

[yehoshuadimarsky]

I'm confused - I thought this PR #1513 adds support for OpenAPI spec version 3.x? But I don't see the CLI option openAPIVersionFlag

[N214]

I'm confused - I thought this PR #1513 adds support for OpenAPI spec version 3.x? But I don't see the CLI option openAPIVersionFlag

Compile the latest release by yourself and you'll see it.

[Nerzal]

The v3.1.0 implementation still has some bugs that need to be fixed

[vamshiaruru32]

Looking forward to the 3.1.0 support as well ^-^

[svennjegac]

Hoping we will get 3.1.0 support 🤞

[PanGan21]

Hi! What is the status of this issue? Is there a chance that we will get 3.1.0 support any time soon?