Easily visualize and interact with your REST API in your Vaadin project.

Status: Public Beta 🎉 Sponsor Program 💖 Follow me @F0rceDev 🐦

Technical structure

• Swagger UI has been packaged as a web component using Lit (<lit-swagger-ui>)
• Swagger Editor has be replicated using my own ace and <lit-swagger-ui> in a Vaadin SplitLayout

Future plans

Currently there is limited to none further functionality / customization besides setting the spec in <lit-swagger-ui> (which is sufficient in my current use case). If there is enough interest or some interesting use cases I am willing to maintain this Vaadin Add-on actively.
If you are missing some functionality or have a feature request please open a new issue.

Install

Install the component using Vaadin Directory or by adding the swagger-*.jar from the latest release to your project.

Example Usage

Swagger Editor (SplitLayout)

@Route("")
public class TestView extends Div {

  public TestView() {
    // Set the parent <div> to full size (fullscreen)
    this.setSizeFull();

    // Initialize new SwaggerEditor aka SplitView with AceEditor as primary and SwaggerUI as
    // secondary
    SwaggerEditor swaggerEditor = new SwaggerEditor();

    // Add the spec as soon as SwaggerUI is ready --> this is not neccessary, as the frontend
    // handles it automatically
    swaggerEditor
        .getSwaggerUI()
        .addReadyListener(
            event -> {
              // OpenAPI 3.0 sample
              swaggerEditor.setSpec(
                  "openapi: 3.0.0\n"
                      + "info:\n"
                      + "  version: 1.0.0\n"
                      + "  title: Sample API\n"
                      + "  description: A sample API to illustrate OpenAPI concepts\n"
                      + "paths:\n"
                      + "  /list:\n"
                      + "    get:\n"
                      + "      description: Returns a list of stuff              \n"
                      + "      responses:\n"
                      + "        '200':\n"
                      + "          description: Successful response");
            });

    // Add SwaggerEditor to the parent <div>
    this.add(swaggerEditor);
  }
}

Swagger UI (Standalone)

@Route("")
public class TestView extends Div {

  public TestView() {
    // Set the parent <div> to full size (fullscreen)
    this.setSizeFull();

    // Initialize new SwaggerUI
    SwaggerUI swaggerUI = new SwaggerUI();

    // Set the size to fullscreen to match parents height/width
    swaggerUI.setSizeFull();

    swaggerUI.addReadyListener(
        event -> {
          // OpenAPI 3.0 sample
          swaggerUI.setSpec(
              "openapi: 3.0.0\n"
                  + "info:\n"
                  + "  version: 1.0.0\n"
                  + "  title: Sample API\n"
                  + "  description: A sample API to illustrate OpenAPI concepts\n"
                  + "paths:\n"
                  + "  /list:\n"
                  + "    get:\n"
                  + "      description: Returns a list of stuff              \n"
                  + "      responses:\n"
                  + "        '200':\n"
                  + "          description: Successful response");
        });

    // Add SwaggerUI to the parent <div>
    this.add(swaggerUI)
  }
}

Customizing Ace

If you want to change the default behaviour of ace you can access the instance using:

SwaggerEditor swaggerEditor = new SwaggerEditor();
AceEditor ace = swaggerEditor.getAceEditor();

// turn of read-only mode
ace.setReadOnly(false);

Please refer to ace's documentation for further information.

Documentation

docs.f0rce.de/vaadin-swagger

Licence

MIT License © 2022 David Dodlek