From 582c9a72ee1776182ab1b80218a9aff3e6c5bbbc Mon Sep 17 00:00:00 2001 From: joshua bauer Date: Wed, 9 Jan 2019 15:37:24 -0800 Subject: [PATCH] Updated readme. --- README.md | 77 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 63 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 366c381..17ecadb 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ An extremely __lightweight, flexible, and high performance__ [Undertow](http://undertow.io) based Java framework for developing RESTful web applications and microservices. - __NO MAGIC__ -- Lightweight: limited dependencies and < 400kb +- Lightweight: limited dependencies and < 340kb - JAX-RS compliant - Easy on the developer and the metal - Blazing fast!!! @@ -30,7 +30,8 @@ Getting Started /bin/bash -e <(curl -fsSL https://raw.githubusercontent.com/noboomu/proteus-example/master/scripts/quickStart.sh) ``` -- Open [http://localhost:8090/v1/openapi](http://localhost:8090/v1/openapi) for a v3 Swagger UI. +- Open [http://localhost:8090/v1/openapi](http://localhost:8090/v1/openapi) for a v3 OpenAPI UI. +- Open [http://localhost:8090/v1/swagger](http://localhost:8090/v1/openapi) for a v2 Swagger UI. ### As a dependency @@ -38,7 +39,25 @@ Getting Started io.sinistral proteus-core - 0.3.6 + 0.4.0-SNAPSHOT + +``` + +Swagger v2 Support +```xml + + io.sinistral + proteus-swagger + 0.4.0-SNAPSHOT + +``` + +OpenAPI v3 Support +```xml + + io.sinistral + proteus-swagger + 0.4.0-SNAPSHOT ``` @@ -47,12 +66,12 @@ Controllers ### Supported Controller Annotations -Controller classes respect standard Swagger / JAX-RS annotations: +Controller classes respect standard JAX-RS annotations: ```java -@Tags({@Tag(name = "benchmarks")}) @Path("/benchmarks") @Produces((MediaType.APPLICATION_JSON)) @Consumes((MediaType.MEDIA_TYPE_WILDCARD)) +public class DemoController ``` ### Supported Method Annotations @@ -62,12 +81,16 @@ Controller class methods respect standard Swagger / JAX-RS annotations: @GET @Path("/plaintext") @Produces((MediaType.TEXT_PLAIN)) -@Operation(description = "Plaintext endpoint" ) public ServerResponse plaintext(ServerRequest request) { return response("Hello, World!").textPlain(); } ``` + +> Swagger v2 annotations are supported when using the `proteus-swagger` module. + +> OpenAPI v3 annotations are supported when using the `proteus-openapi` module. + Proteus has three built in annotations: * @Blocking @@ -113,7 +136,9 @@ Controller methods arguments support the following [JAX-RS annotations](https:// * ```javax.ws.rs.DefaultParam``` * Sets the default value of a method parameter. -## Return Types +## Methods and Return Types + +###### *The examples below assume you've included the `proteus-openapi` module. #### Performance For total control and maximum performance the raw `HttpServerExchange` can be passed to the controller method. @@ -123,25 +148,33 @@ Methods that take an `HttpServerExchange` as an argument should __not__ return a In this case the method takes on __full responsibility__ for completing the exchange. #### Convenience + + The static method ```io.sinistral.proteus.server.ServerResponse.response``` helps create ```ServerResponse``` instances that are the preferred return type for controller methods. If the response object's `contentType` is not explicitly set, the `@Produces` annotation is used in combination with the `Accept` headers to determine the `Content-Type`. For methods that should return a `String` or `ByteBuffer` to the client users can create responses like this: ```java + ... + import static io.sinistral.proteus.server.ServerResponse.response; + ... @GET @Path("/hello-world") @Produces((MediaType.TEXT_PLAIN)) @Operation(description = "Serve a plaintext message using a ServerResponse") public ServerResponse plaintext(ServerRequest request, @QueryParam("message") String message) { - return ServerResponse.response("Hello, World!").textPlain(); + return response("Hello, World!").textPlain(); } ``` By default, passing a `String` to the static `ServerResponse.response` helper function will convert it into a `ByteBuffer`. For other types of responses the following demonstrates the preferred style: ```java + ... + import static io.sinistral.proteus.server.ServerResponse.response; + ... @GET @Path("/world") @Produces((MediaType.APPLICATION_JSON)) @@ -155,19 +188,25 @@ The entity can be set separately as well: > this disables static type checking! ```java + ... + import static io.sinistral.proteus.server.ServerResponse.response; + ... @GET @Path("/world") @Produces((MediaType.APPLICATION_JSON)) @Operation(description = "Return a world JSON object") -public io.sinistral.proteus.server.ServerResponse getWorld(Integer id, Integer randomNumber ) +public ServerResponse getWorld(Integer id, Integer randomNumber ) { - return io.sinistral.proteus.server.ServerResponse.response().entity(new World(id,randomNumber)); + return response().entity(new World(id,randomNumber)); } ``` `CompletableFuture>` can also be used as a response type: ```java + ... + import static io.sinistral.proteus.server.ServerResponse.response; + ... @GET @Path("/future/user") @Operation(description = "Future user endpoint" ) @@ -180,6 +219,9 @@ public CompletableFuture> futureUser( ServerRequest request In this case a handler will be generated with the following source code: ```java + ... + import static io.sinistral.proteus.server.ServerResponse.response; + ... public void handleRequest(final io.undertow.server.HttpServerExchange exchange) throws java.lang.Exception { CompletableFuture> response = examplesController.futureUser(); response.thenAccept( r -> r.applicationJson().send(this,exchange) ) @@ -200,6 +242,9 @@ Multipart/Form file uploads can be passed to the endpoint methods as a ```java.i Optional parameters are also supported, here is a more complex endpoint demonstrating several parameter types: ```java + ... + import static io.sinistral.proteus.server.ServerResponse.response; + ... @GET @Path("/response/parameters/complex/{pathLong}") @Operation(description = "Complex parameters") @@ -242,9 +287,12 @@ public ServerResponse> complexParameters( Services ------------- -Proteus comes with three standard services that extend the ```io.sinistral.proteus.services.BaseService``` class. +Proteus has three standard services that extend the ```io.sinistral.proteus.services.BaseService``` class. + - __AssetsService__ + Included in the `proteus-core` module. + The AssetsService mounts an asset directory at a given path and is configured in your ```application.conf``` file. The default configuration: @@ -262,6 +310,8 @@ Proteus comes with three standard services that extend the ```io.sinistral.prote ``` - __SwaggerService__ + Included in the `proteus-swagger` module. + The SwaggerService generates a swagger-spec file from your endpoints and serves a swagger-ui and spec. The default configuration serves the spec at `{application.path}/swagger.json` and the ui at `${application.path}/swagger`. @@ -272,7 +322,6 @@ Proteus comes with three standard services that extend the ```io.sinistral.prote ``` swagger { # the path that has an index.html template and theme css files - resourcePrefix="io/sinistral/proteus/swagger" # swagger version swagger: "2.0" info { @@ -299,6 +348,8 @@ Proteus comes with three standard services that extend the ```io.sinistral.prote - __OpenAPIService__ + Included in the `proteus-openapi` module. + The OpenAPIService generates an openapi-spec file from your endpoints and serves a swagger-ui and spec. The default configuration serves the spec at `{application.path}/openapi.yaml` and the ui at `${application.path}/openapi`. @@ -309,8 +360,6 @@ Proteus comes with three standard services that extend the ```io.sinistral.prote ``` openapi { - resourcePrefix="io/sinistral/proteus/server/tools/openapi" - basePath= ${application.path}"/openapi" port = ${application.ports.http}