Git Product home page Git Product logo

swaggerservlet's Introduction

SwaggerServlet

A very simple framework that validates REST requests with Swagger and routes them to Pojo classes

SwaggerServlet also provides useful features:

  • A monitoring URL like /api/v1/test that tests the web service and its dependencies;
  • A documentation URL like /api/v1/swagger-ui that opens swagger-ui showing your API;
  • Declared (and validated) environment parameters.

Main objectives are:

  • To be very small and simple;
  • To enforce consistency by using typed data;
  • To have minimum dependencies.

A very simple usage example can be seen here, and the respective swagger.yaml is here.

A more complex, real life usage example, can be seen here.

Using it through Maven

For a quick start, you can use this snippet in your maven POM:

<dependency>
    <groupId>com.crivano</groupId>
    <artifactId>swaggerservlet</artifactId>
    <version>1.34.0</version>
</dependency>

Architecture

SwaggerServlet requires a swagger.yaml file and a Java interface with declarations for all methods inputs and outputs. It's also necessary to declare a HttpServlet that extends SwaggerServlet class, and to have a Pojo for each web service method.

In order to reuse the web service's contract, one can create a project containing only the swagger.yaml and the Java interface, as can be seen in this example.

SwaggerServlet-UI

SwaggerServlet has an accompanying website that is capable of generating a Java interface from a swagger.yaml file. For instance:

swaggerservlet appspot com_(Desktop PC) (1)

It is also possible to create a diagram of the dependencies using the SwaggerServlet-UI tool. For example:

swaggerservlet appspot com_(Desktop PC)

Dependencies

When a web service depends on another, it can be declared like this:

addDependency(new SwaggerServletDependency("webservice", system, false, 0, 10000) {
    @Override
    public String getUrl() {
        return "https:example.com/;
    }
});

SwaggerServletDependecy constructor parameters are: service's category, service's name, a boolean to indicate a partial dependency, minimum time necessary to test de dependency in milliseconds and maximum wait time to test de dependency.

A generic dependency can be declared like this:

addDependency(new TestableDependency("cache", "redis", false, 0, 10000) {
    @Override
    public String getUrl() {
        return "redis://redis.example.com";
    }
    @Override
    public boolean test() throws Exception {
        String uuid = UUID.randomUUID().toString();
        MemCacheRedis mc = new MemCacheRedis();
        mc.store("test", uuid.getBytes());
        String uuid2 = new String(mc.retrieve("test"));
        return uuid.equals(uuid2);
    }
});

Properties

Every service can be customized with many parameters. Usually these parameters are defined in JBoss' standalone.xml or other App Server configuration file. The problem is that sometimes it gets difficult to track all these parameters. SwaggerServlet offers the possibility of declaring all the necessary parameters and giving default values to some. The complete list of parameters is returned by the /api/v1/test url. It is also possible to set parameters as public, restricted or private. For example:

addPublicProperty("redis.url");
addRestrictedProperty("redis.database", "10");
addPrivateProperty("redis.password", null);

In the above example, the first parameter tells the name of the property and the last says if it has a default value. Properties that miss the default value will cause an error if they are not present in the configuration files.

All properties are prefixed with the name of the servlet's context. For instance, if the webapp is installed at "https://assijus.trf2.jus.br/assijus", the "redis.url" property above should be declared at standalone.xml as "assijus.redis.url".

Properties not found in the configuration files are searched among environment variables. If SwaggerServlet can't find "assijus.redis.url" at the standalone.xml properties, it will try to find the environment variable PROP_ASSIJUS_REDIS_URL instead. This is very useful when instantiating a web server with docker-compose.

swaggerservlet's People

Contributors

crivano avatar dinarde avatar markenson avatar

Watchers

 avatar  avatar  avatar

Forkers

dinarde

swaggerservlet's Issues

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.