Swagger

Overview

Elide supports the generation of Swagger documentation from Elide annotated beans. Specifically, it generates a JSON documentconforming to the swagger specification that can be used by tools like Swagger UI (among others) to explore, understand, and compose queries againstyour Elide API.

Features Supported

  • JaxRS Endpoint - Elide ships with a customizable JaxRS endpoint that can publish one or more swagger documents.
  • Path Discovery - Given a set of entities to explore, Elide will generate the minimum, cycle-free, de-duplicated set of URL paths in the swagger document.
  • Filter by Primitive Attributes - All GET requests on entity collections include filter parameters for each primitive attribute.
  • Prune Fields - All GET requests support JSON-API sparse fields query parameter.
  • Include Top Level Relationships - All GET requests support the ability to include direct relationships.
  • Sort by Attribute - All GET requests support sort query parameters.
  • Pagination - All GET requests support pagination query parameters.
  • Permission Exposition - Elide permissions are exported as documentation for entity schemas.

    Getting Started

Maven

Pull in the following elide dependencies :

  1. <dependency>
  2.   <groupId>com.yahoo.elide</groupId>
  3.   <artifactId>elide-swagger</artifactId>
  4. </dependency>
  6. <dependency>
  7.   <groupId>com.yahoo.elide</groupId>
  8.   <artifactId>elide-core</artifactId>
  9. </dependency>

Pull in swagger core :

  1. <dependency>
  2.   <groupId>io.swagger</groupId>
  3.   <artifactId>swagger-core</artifactId>
  4. </dependency>

Basic Setup

Create and initialize an entity dictionary.

  1. EntityDictionary dictionary = new EntityDictionary(Maps.newHashMap());
  3. dictionary.bindEntity(Book.class);
  4. dictionary.bindEntity(Author.class);
  5. dictionary.bindEntity(Publisher.class);

Create a swagger info object.

  1. Info info = new Info().title("My Service").version("1.0");

Initialize a swagger builder.

  1. SwaggerBuilder builder = new SwaggerBuilder(dictionary, info);

Build the document & convert to JSON.

  1. Swagger document = builder.build();
  2. String jsonOutput = SwaggerBuilder.getDocument(document);

Supporting OAuth

If you want swagger UI to acquire & use a bearer token from an OAuth identity provider, you can configurethe swagger document similar to:

  1. SecuritySchemeDefinition oauthDef = new OAuth2Definition().implicit(CONFIG_DATA.zuulAuthorizeUri());
  2. SecurityRequirement oauthReq = new SecurityRequirement().requirement("myOuath");
  4. SwaggerBuilder builder = new SwaggerBuilder(entityDictionary, info);
  5. Swagger document = builder.build();
  6.     .basePath("/my/url/path")
  7.     .securityDefinition("myOauth", oauthDef)
  8.     .security(oauthReq)
  9.     .scheme(Scheme.HTTPS));

Adding a global parameter

A query or header parameter can be added globally to all Elide API endpoints:

  1. HeaderParameter oauthParam = new HeaderParameter()
  2.     .name("Authorization")
  3.     .type("string")
  4.     .description("OAuth bearer token")
  5.     .required(false);
  7. SwaggerBuilder crashBuilder = new SwaggerBuilder(dictionary, info)
  8.     .withGlobalParameter(oauthParam);

Adding a global response code

An HTTP response can be added globally to all Elide API endpoints:

  1. Response rateLimitedResponse = new Response().description("Too Many Requests");
  3. SwaggerBuilder crashBuilder = new SwaggerBuilder(dictionary, info)
  4.     .withGlobalResponse(429, rateLimitedResponse);

Performance

Path Generation

The Swagger UI is very slow when the number of generated URL paths exceeds a few dozen. For large, complex data models, it is recommended to generate separate swagger documents for subgraphs of the model.

  1. Set<Class<?>> entities = Sets.newHashSet(
  2.     Book.class,
  3.     Author.class,
  4.     Publisher.class
  5. );
  7. SwaggerBuilder coreBuilder = new SwaggerBuilder(dictionary, info)
  8.     .withExplicitClassList(entities);

In the above example, swagger will only generate paths that exclusively traverse the provided set of entities.

Document Size

The size of the swagger document can be reduced significantly by limiting the number of filter operators that are used to generate query parameterdocumentation.

  1. SwaggerBuilder crashBuilder = new SwaggerBuilder(dictionary, info)
  2.    .withFilterOps(Sets.newHashSet(Operator.IN));

In the above example, filter query parameters are only generated for the IN operator.

原文: http://elide.io/pages/guide/13-swagger.html