Supprt OpenAPI Specification Version 3.0.2

Question

Supprt OpenAPI Specification Version 3.0.2

kshamiev opened this issue 6 years ago · 22 comments

kshamiev commented 6 years ago

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

Answer 1 · 2019-05-07T13:54:30.000Z

Do you know good openapi v3 spec library for go ?

Answer 2 · 2019-05-09T08:35:08.000Z

kin-openapi ,is it okay?

Answer 3 · 2019-09-23T11:14:16.000Z

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).

Answer 4 · 2021-03-31T10:55:05.000Z

Hi guys,
any updates?

Answer 5 · 2021-05-06T22:25:59.000Z

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

Answer 6 · 2021-07-15T02:38:28.000Z

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 ?

Answer 7 · 2021-07-15T03:05:49.000Z

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

Answer 8 · 2021-07-15T08:41:06.000Z

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

Answer 9 · 2021-09-17T21:02:56.000Z

uppppppppppppppppppp

Answer 10 · 2021-09-17T21:10:16.000Z

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

Answer 11 · 2021-09-17T21:16:23.000Z

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

Answer 12 · 2021-09-18T06:21:13.000Z

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

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

Answer 13 · 2022-05-02T10:18:08.000Z

Any update?

Answer 14 · 2023-02-18T19:35:27.000Z

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

Answer 15 · 2023-02-18T22:44:09.000Z

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?

Answer 16 · 2023-03-03T11:05:35.000Z

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

Answer 17 · 2023-07-07T00:34:07.000Z

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

Answer 18 · 2023-07-10T03:57:01.000Z

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.

Answer 19 · 2023-07-10T06:37:46.000Z

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

Answer 20 · 2023-07-13T01:45:09.000Z

Looking forward to the 3.1.0 support as well ^-^

Answer 21 · 2023-10-19T14:59:15.000Z

Hoping we will get 3.1.0 support 🤞

Answer 22 · 2024-06-04T16:07:33.000Z

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