Supprt OpenAPI Specification Version 3.0.2

kshamiev commented 5 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

pei0804 commented 5 years ago

Do you know good openapi v3 spec library for go ?

chenjpu commented 5 years ago

kin-openapi ,is it okay?

betabandido commented 5 years ago

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

serg-kovalev commented 3 years ago

Hi guys, any updates?

OneCricketeer commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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

lifegit commented 3 years ago

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

hotrungnhan commented 3 years ago

uppppppppppppppppppp

hotrungnhan commented 3 years ago

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

OneCricketeer commented 3 years ago

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

hotrungnhan commented 3 years ago

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

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

thetruechar commented 2 years ago

Any update?

s4l1h commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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

yehoshuadimarsky commented 1 year ago

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