Upgrade codegen tools in scripts/generate-open-api-spec and publish Swagger 2.0 and OpenAPI 3.0 specs

[ff137]

Now is as good a time as any to upgrade the codegen tools in scripts/generate-open-api-spec to use the latest swaggerapi/swagger-codegen-cli release (it was ~3 years out of date).

Additionally, I added the latest openapitools/openapi-generator-cli, so that the spec generation now provides both a Swagger 2.0 spec, and an OpenApi 3.0 spec. This way users don't need to manually upgrade the spec themselves.

Previously the Swagger 2.0 spec was simply called openapi.json. This is now renamed swagger.json, with the 3.0 compatible spec in its place.

Worth noting that the spec validation still only throws warnings that can be ignored:

• the swagger spec validation only complains about some missing operationId's (and 'host' not defined);
• and the open-api spec validation only complains about example fields being unexpected, and a single case of attribute tags.tagsexternalDocs.url is missing.

Also, I updated the UsingOpenAPI.md file to reflect these changes, with some minor neatening up included.

Review can be validated by running scripts/generate-open-api-spec.

Discussion re further edits is welcome.

[ff137]

@swcurran I was thinking it may be worthwhile to add an OpenAPI Spec Generation to the CI workflow. Something like:

name: OpenAPI Spec Check

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2

    - name: Setup environment
      run: |
        # setup necessary environment

    - name: Generate OpenAPI specs
      run: |
        ./scripts/generate-open-api-spec

    - name: Commit changes
      run: |
        git config --local user.email "[email protected]"
        git config --local user.name "GitHub Action"
        git commit -m "Update Swagger/OpenAPI specs" -a

What do you think?

[sonarqubecloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
No Duplication information

[swcurran]

Nice work — looks good. There sure are a lot of errors generated!!! I’m assuming that is expected/OK, given that things are working.

@jcourt562 — any thoughts on the idea of a GHA to generate the openapi JSON?

[ff137]

@swcurran Thanks!

I would say the warnings are low priority to fix, but always worth it in the long run.

It's mainly:

• setting operationIds everywhere
• adding the one missing doc URL
  • it's for: description: did resolver interface.
  • I think this may be the appropriate link: https://github.com/hyperledger/aries-rfcs/tree/070b325ef4a55005d79d03eb629f0399f3a0dfc4/features/0124-did-resolution-protocol, but I may be wrong.
• no server url being set

The UsingOpenAPI.md does say (2 years ago) aiohttp_apispec does not support adding operationId annotations via tags. Maybe that's changed.

I do have a script for patching an openapi.yml with a mapping of operation-ids. Maybe that feels like a more maintainable solution than tagging? Because then you can manage all operation id's in one file. Let me know and I can add it.

As for all the: -attribute paths ... .example is unexpected errors, I have no idea. Looking at the spec doesn't really line up with path being reported -- maybe someone else can figure that one out!