Update Swagger to OpenAPI 3.0 for Enabling JWT

[steffes]

It is not possible to generate clients from swagger 2.0 when common.yaml contains type: JWT which is an OpenAPI 3.0 feature. See: swagger-api/swagger-ui#3860 (comment)

[luke-]

Thank you for the PR.

For some reason I cannot build the redoc HTML doc with your change..

$ ./build-all.sh
--------- activity.yaml ---------------------
Prerendering docs

🎉 bundled successfully in: ../html/activity.html (52 KiB) [⏱ 0.363s]
--------- auth.yaml ---------------------
Prerendering docs

🎉 bundled successfully in: ../html/auth.html (38 KiB) [⏱ 0.189s]
--------- calendar.yaml ---------------------
Prerendering docs

🎉 bundled successfully in: ../html/calendar.html (86 KiB) [⏱ 0.374s]
--------- cfiles.yaml ---------------------
Prerendering docs

🎉 bundled successfully in: ../html/cfiles.html (92 KiB) [⏱ 0.433s]
--------- comment.yaml ---------------------
Prerendering docs

🎉 bundled successfully in: ../html/comment.html (42 KiB) [⏱ 0.179s]
--------- common.yaml ---------------------
Prerendering docs
TypeError: Cannot read property 'description' of undefined
    at new ApiInfoModel (/usr/lib/node_modules/redoc-cli/node_modules/redoc/bundles/redoc.lib.js:8275:45)
    at new SpecStore (/usr/lib/node_modules/redoc-cli/node_modules/redoc/bundles/redoc.lib.js:8626:21)
    at new AppStore (/usr/lib/node_modules/redoc-cli/node_modules/redoc/bundles/redoc.lib.js:10511:21)
    at Module.<anonymous> (/usr/lib/node_modules/redoc-cli/node_modules/redoc/bundles/redoc.lib.js:10495:43)
    at step (/usr/lib/node_modules/redoc-cli/node_modules/tslib/tslib.js:136:27)
    at Object.next (/usr/lib/node_modules/redoc-cli/node_modules/tslib/tslib.js:117:57)
    at fulfilled (/usr/lib/node_modules/redoc-cli/node_modules/tslib/tslib.js:107:62)

Any idea?

[steffes]

common.yaml is not valid swagger: 2.0. title, version, and paths are required. Paths may be empty.

Using the https://mermade.org.uk/openapi-converter I got the following result that is missing the preexisting components:

openapi: 3.0.0
info:
  version: ""
  title: ""
paths: {}

components:
  securitySchemes:
    Bearer:
      type: JWT
      name: Authorization
      in: header
    BasicAuth:
      type: http
      scheme: basic
  schemas:
    ContainerNotFound:
      description: Not found
      schema:
        type: object
        properties:
          code:
            type: integer
            example: 404
          message:
            type: string
            example: Content container not found!

Need to figure out the proper conversion of components: parameters: and components: properties:. Know of any tools that do it?

When creating my client code, I bundle and dereference so I am skipping common.yaml because it's bundled.

[luke-]

Besides the common file problem, are you still able to generate the HTML documentation with your changes?

https://github.com/humhub/humhub-modules-rest/blob/master/docs/swagger/build-all.sh

[steffes]

No I get the same build error as you. All the files need to be refactored much more to be OpenAPI 3.0. I am closing this and will try to make a better PR with everything properly updated.

[luke-]

That would be awesome!

We don't necessarily have to use Redec to build the HTML documentation, but the SinglePages doc without any dependencies (JS/Images) was very convenient.