swag
swag copied to clipboard
swaggo
Supprt OpenAPI Specification Version 3.0.2
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
It does not look like go-openapi will support openapi 3 any time soon. See:
https://github.com/go-openapi/spec/issues/21 https://github.com/go-openapi/spec3/issues/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).
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
I've worked around this with some Make targets
The first runs
swag initon the root project, creating thedocs/swagger.jsonanddocs/swagger.yamlThe 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 ?
@lifegit Create a Makefile with that content, and run the command I mentioned
@hotrungnhan What about it? It was already mentioned in the third comment
@hotrungnhan What about it? It was already mentioned in the third comment
oh im sorry i did't read thi third comment.
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
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?
I'm confused - I thought this PR https://github.com/swaggo/swag/pull/1513 adds support for OpenAPI spec version 3.x? But I don't see the CLI option openAPIVersionFlag
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.
