Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Supprt OpenAPI Specification Version 3.0.2 #386

Open
kshamiev opened this issue May 1, 2019 · 22 comments
Open

Supprt OpenAPI Specification Version 3.0.2 #386

kshamiev opened this issue May 1, 2019 · 22 comments
Labels

Comments

@kshamiev
Copy link

kshamiev commented May 1, 2019

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
Copy link
Member

pei0804 commented May 7, 2019

Do you know good openapi v3 spec library for go ?

@chenjpu
Copy link

chenjpu commented May 9, 2019

kin-openapi ,is it okay?

@betabandido
Copy link

betabandido commented Sep 23, 2019

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
Copy link

Hi guys,
any updates?

@OneCricketeer
Copy link

OneCricketeer commented May 6, 2021

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
Copy link

lifegit commented Jul 15, 2021

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
Copy link

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

@lifegit
Copy link

lifegit commented Jul 15, 2021

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

@hotrungnhan
Copy link

uppppppppppppppppppp

@hotrungnhan
Copy link

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

@OneCricketeer
Copy link

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

@hotrungnhan
Copy link

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

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

@thetruechar
Copy link

Any update?

@s4l1h
Copy link

s4l1h commented Feb 18, 2023

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
Copy link
Contributor

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
Copy link

@yehoshuadimarsky
Copy link

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
Copy link

N214 commented Jul 10, 2023

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
Copy link
Contributor

Nerzal commented Jul 10, 2023

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

@vamshiaruru32
Copy link

Looking forward to the 3.1.0 support as well ^-^

@svennjegac
Copy link

Hoping we will get 3.1.0 support 🤞

@PanGan21
Copy link

PanGan21 commented Jun 4, 2024

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests