swagger-api / swagger-ui

Swagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.
https://swagger.io
Apache License 2.0
26.52k stars 8.96k forks source link

Sorting or grouping annotated classes via java? #1020

Closed LingLong closed 9 years ago

LingLong commented 9 years ago

I implemented swagger-ui like this:

...
//Swagger beanconfig
BeanConfig beanConfig = new BeanConfig();
//beanConfig.setVersion("1.0");
beanConfig.setResourcePackage("de.unileipzig.irpsim.backend"); //StartSimulation.class.getPackage().getName()
beanConfig.setBasePath(uri);
beanConfig.setDescription("Hello resources");
beanConfig.setTitle("Hello API");
beanConfig.setScan(true);
...
//Httphandler fuer SwaggerUI
CLStaticHttpHandler staticHttpHandler = new CLStaticHttpHandler(ServerStarter.class.getClassLoader(), "swagger-ui/");
server.getServerConfiguration().addHttpHandler(staticHttpHandler);
...

everything works fine, i also annotated some classes like this:

@Path("simulations")
@Api(value = "/simulations", description="Starten / Beenden einer Simulation")
public class SimulationEndpoint {...}
...
@Path("simulations/{simulationid}")
@Api(value = "/simulations/{simulationid}", description="TODO")
@Produces({"application/json"})
public class SimulationJobEndpoint {...}

The "problem " is that swagger-ui is showing me the following:

/simulations
/someOtherClass...
...
...
/{simulationid}

Now I want swagger-ui to show me these classes together in same order, because they are following the same path. Is there any way to do this?

Thanks for your help!

webron commented 9 years ago

Which version of swagger-core do you use?

What do you mean by 'show me these classes together'?

SwaggerUI has controls the ordering of the operations based on the sorter parameter described here - https://github.com/swagger-api/swagger-ui#parameters.

LingLong commented 9 years ago

I use version 1.3.12 What i meant was, that the apidoc-entries should appear in order, odered by thair paths. So, if /simulations appears in apidoc the next entry to should be /simulations/{simulationid}.

webron commented 9 years ago

Then just set the sorter for SwaggerUi.

LingLong commented 9 years ago

I just took a look at the sorter parameter. The last question is: are there other values for sorter then 'alpha' or 'method' to pass in ?

webron commented 9 years ago

I think it can accept a sorting function as well.

LingLong commented 9 years ago

Ok, thank you for your help!

LingLong commented 9 years ago

I hope it is possible to open this issue again, because sorter only seems to sort annotated methods. But I like to sort resources. Better question is how could I tell swagger-ui that a resource is child of another resource?

webron commented 9 years ago

There's no hierarchy for operations. There's only grouping, and within those groups you can sort the operations. That's pretty much it.

LingLong commented 9 years ago

Coud you please show me an example of Grouping?

LingLong commented 9 years ago

I just red swagger-spec:

  1. Definitions

Resource: A resource in Swagger is an entity that has a set of exposed operations. The entity can represent an actual object (pets, users..) or a set of logical operations collated together. It is up to the specification user to decide whether sub-resources should be referred to as part of their main resource or as a resource of their own. For example, assume the following URL set:

URL: A fully qualified URL.

But I do not understand the goal of this article. How to reffere sub-resource as part of a main-resource?

fehguy commented 9 years ago

there's an example here:

http://generator.swagger.io/

Note how some operations appear under each "tag", which is clients or servers. The code is here:

https://github.com/swagger-api/swagger-codegen/blob/develop_2.0/modules/swagger-generator/src/main/java/com/wordnik/swagger/generator/resource/SwaggerResource.java

If you look at the operation path /download/{fileId}, you'll see that it's assigned to two tags. This is how you control where operations appear in the UI.

LingLong commented 9 years ago

ok, i also found another solution for myself, maybe its a bit dirty. i only added the following line of code in swagger-client.js between lines 1838-1844: response.apis.sort(function(a,b) { return a.path.localeCompare(b.path) } );

this will sort response.apis in the right order

LingLong commented 9 years ago

Thank you really much for your help.