search

zircote / swagger-php

A php swagger annotation and parsing library
http://zircote.github.io/swagger-php/
Apache License 2.0
5.03k stars 933 forks source link

Unable to group #1609

Closed caixingyue closed 2 weeks ago

caixingyue commented 3 weeks ago

I searched through the documentation but couldn't find a way to implement the method shown in the figure. In Java, you can add groups by

.group("admin")
.pathsToMatch("/admin_api/**")

image

DerManoMann commented 3 weeks ago

Must be a feature of the specific library. What exactly does this change in the generated spec? I do not remember groups as an open API concept?

caixingyue commented 3 weeks ago

Must be a feature of the specific library. What exactly does this change in the generated spec? I do not remember groups as an open API concept?

It is a common scenario that there are multiple system interfaces for the same Laravel. Generally, we provide different interfaces to third-party partners, apps, operation backgrounds, etc., and there will be different prefix routes depending on the situation. How should we provide documents for this scenario? Putting them directly in one document will be bloated because they do not need interfaces with different routes.

In spring, we will directly use the grouping method.

DerManoMann commented 3 weeks ago

Fair enough, that is roughly what I thought the reason might be.

Ah, I missed that dropdown - never seen that before. So far the only way I knew of is using tags.

So, my question again - how does this grouping look like in the actual generated Yaml/Json if it is not tags? I just checked out the latest swagger-ui and I cannot see the dropdown at all...?

caixingyue commented 3 weeks ago

Fair enough, that is roughly what I thought the reason might be.

Ah, I missed that dropdown - never seen that before. So far the only way I knew of is using tags.

So, my question again - how does this grouping look like in the actual generated Yaml/Json if it is not tags? I just checked out the latest swagger-ui and I cannot see the dropdown at all...?

If you use tags, they will still be displayed on the same page, so that no matter which system's APIs are, they will be displayed together, which is not appropriate. At present, I have simply checked the source code, and it seems that multiple documents can be generated, but they cannot be switched like groups, and there is no relevant document that mentions how to generate multiple documents.

DerManoMann commented 3 weeks ago

Could you please post a sample of a document that contains that grouping you want? I think we need to work backwards from that. Maybe this is a custom extension of the Spring library?

caixingyue commented 3 weeks ago

Could you please post a sample of a document that contains that grouping you want? I think we need to work backwards from that. Maybe this is a custom extension of the Spring library?

He generates multiple json files based on the group name, and then when switching in the UI, it will jump to different json.

As I mentioned earlier, l5-swagger also has this implementation, but it seems not perfect?

caixingyue commented 3 weeks ago

@DerManoMann

For example, if there are these two configuration methods in spring, two api-docs will be generated. In the UI, there will be tabs for switching. You are right, I think this is indeed not the swagger specification, but it is a very useful extension.

GroupedOpenApi.builder().group("starcore-partner").pathsToMatch("/api/**") http://127.0.0.1:8080/v3/api-docs/starcore-partner

GroupedOpenApi.builder().group("starcore-partner2").pathsToMatch("/api/**") http://127.0.0.1:8080/v3/api-docs/starcore-partner2

DerManoMann commented 3 weeks ago

Ok, I think I have it:

I guess the selector is out of scope (good) :smile:, the grouping could be a feature (also good).

caixingyue commented 3 weeks ago

Ok, I think I have it:

  • The spec selector is the topbar plugin in swagger-ui (core) that allows to toggle between different spec files
  • The group by creates specs using subsets (regexp) of url patterns.

I guess the selector is out of scope (good) 😄, the grouping could be a feature (also good).

Well, for example, if there are multiple configurations, multiple docs can be generated by default, and when there are multiple, the top bar becomes a selector or something like that.

We usually create different routes based on different API systems, and different routes have their own prefixes.

It is very useful to be able to generate different documents based on prefixes, and I am looking forward to seeing such a feature in future versions.