swaggo / swag

Automatically generate RESTful API documentation with Swagger 2.0 for Go.
MIT License
10.46k stars 1.19k forks source link

swag + kiota need the full path name for component #1782

Open chinglinwen opened 5 months ago

chinglinwen commented 5 months ago

Is your feature request related to a problem? Please describe. A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

currently, kiota generate package(a folder) for each unique import path, but we named the component only the suffix name ( for example v1

it cause the go import cycle ( as they are not actually the save v1 package )

Describe the solution you'd like A clear and concise description of what you want to happen.

an option to generate the full import path to name the component, even make it the default behavior

Describe alternatives you've considered A clear and concise description of any alternative solutions or features you've considered.

Additional context Add any other context or screenshots about the feature request here.

I've create a relate issue, https://github.com/microsoft/kiota/issues/4453

both side can fix this issue I think, but create issue here, to solicit maintainer's ideas about this

related issue: https://github.com/swaggo/swag/issues/225, but not solved for this case.

swag version v1.8.10

chinglinwen commented 5 months ago

retried with latest version(v1.16.3)

        "github_com_rook_rook_pkg_apis_ceph_rook_io_v1.Condition": {
            "type": "object",
            "properties": {
                "lastHeartbeatTime": {
                    "type": "string"
                },
                "lastTransitionTime": {
                    "type": "string"
                },
                "message": {
                    "type": "string"
                },
                "reason": {
                    "$ref": "#/definitions/github_com_rook_rook_pkg_apis_ceph_rook_io_v1.ConditionReason"
                },
                "status": {
                    "$ref": "#/definitions/k8s_io_api_core_v1.ConditionStatus"
                },
                "type": {
                    "$ref": "#/definitions/github_com_rook_rook_pkg_apis_ceph_rook_io_v1.ConditionType"
                }
            }
        },
        "github_com_rook_rook_pkg_apis_ceph_rook_io_v1.ConditionType": {
            "type": "string",
            "enum": [
                "Connecting",
                "Connected",
                "Progressing",
                "Ready",
                "Failure",
                "Deleting",
                "DeletionIsBlocked"
            ],
            "x-enum-varnames": [
                "ConditionConnecting",
                "ConditionConnected",
                "ConditionProgressing",
                "ConditionReady",
                "ConditionFailure",
                "ConditionDeleting",
                "ConditionDeletionIsBlocked"
            ]
        },
        "github_com_rook_rook_pkg_apis_ceph_rook_io_v1.NetworkSpec": {
            "type": "object",
            "properties": {
                "connections": {
                    "description": "Settings for network connections such as compression and encryption across the\nwire.\n+nullable\n+optional",
                    "allOf": [
                        {
                            "$ref": "#/definitions/v1.ConnectionsSpec"
                        }
                    ]
                },
                "dualStack": {
                    "description": "DualStack determines whether Ceph daemons should listen on both IPv4 and IPv6\n+optional",
                    "type": "boolean"
                },
                "hostNetwork": {
                    "description": "HostNetwork to enable host network\n+optional",
                    "type": "boolean"
                },
                "ipFamily": {
                    "description": "IPFamily is the single stack IPv6 or IPv4 protocol\n+kubebuilder:validation:Enum=IPv4;IPv6\n+nullable\n+optional",
                    "allOf": [
                        {
                            "$ref": "#/definitions/v1.IPFamilyType"
                        }
                    ]
                },
                "multiClusterService": {
                    "description": "Enable multiClusterService to export the Services between peer clusters\n+optional",
                    "allOf": [
                        {
                            "$ref": "#/definitions/v1.MultiClusterServiceSpec"
                        }
                    ]
                },
                "provider": {
                    "description": "Provider is what provides network connectivity to the cluster e.g. \"host\" or \"multus\"\n+nullable\n+optional",
                    "type": "string"
                },
                "selectors": {
                    "description": "Selectors string values describe what networks will be used to connect the cluster.\nMeanwhile the keys describe each network respective responsibilities or any metadata\nstorage provider decide.\n+nullable\n+optional",
                    "type": "object",
                    "additionalProperties": {
                        "type": "string"
                    }
                }
            }
        },

why it doesn't generate #/definitions/github_com_rook_rook_pkg_apis_ceph_rook_io_v1.ConnectionsSpec, instead it generate #/definitions/v1.ConnectionsSpec

but the "#/definitions/k8s_io_api_core_v1.ConditionStatus" is ok, with full path.

api (generate swagger.json) github.com/rook/rook/pkg/apis ( import by api, type CephCluster = rookv1.CephCluster )

above referenced two different type

NetworkSpec\ https://github.com/rook/rook/blob/master/pkg/apis/ceph.rook.io/v1/types.go#L2391-L2458


Condition https://github.com/rook/rook/blob/master/pkg/apis/ceph.rook.io/v1/types.go#L498-L505

sdghchj commented 5 months ago

If there are definitions with the same name, also from different packages with the same package name, full package path will be used to distinguish them. Otherwise, the package name will be used.

chinglinwen commented 5 months ago

Can we have a flag etc to turn it always using 'full package path' ?