[CI:DOCS] swagger: add operationIds that match with docker

[tmds]

@jwhonce @baude ptal.

I only added operationIds to to match with the docker ones.
You may want to add operationIds to the operations specific to podman too.

[mheon]

I think you need to add [CI:DOCS] to the title to disable full CI, since this is a docs-only change. You will probably need a force-push after that.

Otherwise LGTM

[mheon]

/approve

[openshift-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: mheon, tmds

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [mheon]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[jwhonce]

@tmds If you add [NO TESTS NEEDED] to your commit message, the merge bot will not flag your PR as missing tests.

@baude This PR does show an issue where we have an operationalId conflict between the libpod API and the docker API, SystemVersion is duplicated. Opinion?

[tmds]

@baude This PR does show an issue where we have an operationalId conflict between the libpod API and the docker API, SystemVersion is duplicated. Opinion?

@jwhonce I don't see how there is a duplicate. It looks like distinct swagger sections?

        // swagger:operation GET /version compat CompatSystemVersion
        // ---
        // summary: Component Version information
+       // operationId: SystemVersion
        // tags:
        // - system (compat)
        // produces:
        // - application/json
        // responses:
        //   200:
        //    $ref: "#/responses/Version"
        r.Handle("/version", s.APIHandler(compat.VersionHandler)).Methods(http.MethodGet)
        r.Handle(VersionedPath("/version"), s.APIHandler(compat.VersionHandler)).Methods(http.MethodGet)
        // swagger:operation GET /libpod/version libpod SystemVersion

It does look like there is a duplicate for ContainerChanges:

        // swagger:operation GET /containers/{name}/changes libpod libpodChangesContainer
        // swagger:operation GET /libpod/containers/{name}/changes compat changesContainer
        // ---
        // tags:
        //   - containers
        //   - containers (compat)
        // summary: Report on changes to container's filesystem; adds, deletes or modifications.
+       // operationId: ContainerChanges
        // description: |

Is the fix to have separate swagger sections for these operations, and only include the operationId in one?

[tmds]

@jwhonce can you take a look at my previous comment?

[jwhonce]

@tmds I saw the conflict between your PR and https://github.com/containers/podman/blob/master/pkg/api/server/register_version.go#L23 regarding the operationId SystemVersion .

Since we have endpoints for the compatibility and libpod in one API we need to namespace them. To fix this across the API, we would need to remove Compat from the Compat on the swagger:operation lines and add Libpod to the libpod operations. If we make those changes, then the swagger processor should gives us your proposed operationId's without having to add operationId to override the one given on the swagger:operation line.

/cc @baude @rhatdan

[tmds]

@jwhonce based on your comment, I've moved the operationIds to the end of the swagger:operation lines. Let me know if I should make additional changes.

[tmds]

Since we have endpoints for the compatibility and libpod in one API we need to namespace them. To fix this across the API, we would need to remove Compat from the Compat on the swagger:operation lines and add Libpod to the libpod operations. If we make those changes

Thinking out loud: you may want to generate separate swagger files, one for libpod, and one for compat. Both of them can use the same operationIds.

[jwhonce]

@tmds I need to think on that suggestion.

Immediate ideas:

• It would fix this issue and supporting /swagger and /libpod/swagger endpoints is trivial.
• Maintenance would be a bit painful since "like" endpoints would be in different files, /containers/json vs /libpod/containers/json
• Generating a client using both API's would bring us back to this issue. Is that a real concern?

/cc @mheon @baude

[vrothberg]

Friendly ping

[github-actions]

A friendly reminder that this PR had no activity for 30 days.

[rhatdan]

@jwhonce @baude @mheon What do we want to do with this?

[jwhonce]

@rhatdan See #9944

[jwhonce]

@tmds I included your commits in #9944 and rebased to master.