Skip to content

Latest commit

 

History

History
145 lines (121 loc) · 6.13 KB

README.md

File metadata and controls

145 lines (121 loc) · 6.13 KB
Raw

Open Text Swagger UI

This project is an Open Text branded version of the Swagger UI.

Usage

It can be used from another Java project by including the following dependency:

<dependency>
    <groupId>com.microfocus.webjars</groupId>
    <artifactId>swagger-ui-dist</artifactId>
</dependency>

To override swagger configuration params include a opentext-config.js file, similar to the one here:

Swagger configuration params that can be set in opentext-config.js:

  • url: "api-docs/swagger.yaml"
  • dom_id: "#swagger-ui
  • operationsSorter: "alpha"
  • tagsSorter: "alpha"
  • docExpansion: "none"
  • defaultModelsExpandDepth: -1
  • deepLinking: true

For a complete list of swagger configuration params refer Swagger configuration params.

Using this module in Spring Boot

  1. Add the module as a runtime dependency.
  2. Include a resource file called opentext-config.js with the swagger configuration overrides, similar to the one here. Make sure to overide the "url" param to point to your swagger contract.
  3. To facilitate serving static resources in Spring Boot override the addResourceHandlers function in
@Override
public void addResourceHandlers(final ResourceHandlerRegistry registry) {

    // Configure the external-facing URI path by adding a resource handler
    final ResourceHandlerRegistration resourceHandlerRegistration = registry.addResourceHandler("/swagger/**");

    // Map that external-facing URI path internally to the physical path where the resources are actually located
    resourceHandlerRegistration.addResourceLocations(
                                    "classpath:/swagger/",
                                    swaggerContractPath,
                                    "classpath:/META-INF/resources/webjars/opentext-swagger-ui-dist/2.0.0/");

    final ResourceChainRegistration resourceChainRegistration = resourceRegistration.resourceChain(true);
    resourceChainRegistration.addResolver(new PathResourceResolver());
}

Using this module in Dropwizard

  1. Add the module as a runtime dependency.
  2. Include a resource file called swagger-ui-config.js to override the swagger configuration, similar to the one here. Make sure to overide the "url" param to point to your swagger contract.
  3. To facilitate serving static resources in Dropwizard add AssetBundles
@Override
public void initialize(Bootstrap<T> bootstrap) {
    bootstrap.addBundle(new AssetsBundle(
        "/META-INF/resources/webjars/opentext-swagger-ui-dist/2.0.0/", "/swagger/", "index.html", "swagger-ui"));
    bootstrap.addBundle(new AssetsBundle(
        "/swagger-ui-config.js", "/swagger/opentext-config.js", null, "swagger-ui-config"));

    super.initialize(bootstrap);
}

Using this module in Tomcat

  1. Include a resource file called opentext-config.js with the swagger configuration overrides, similar to the one here. Make sure to overide the "url" param to point to your swagger contract.
  2. Repackage the swagger assets into the war file to be deployed in Tomcat.

Unpack the swagger-ui artifact excluding the default configuration file

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-dependency-plugin</artifactId>
    <executions>
        <execution>
            <goals>
                <goal>unpack</goal>
            </goals>
            <configuration>
                <artifactItems>
                    <artifactItem>
                        <groupId>com.github.microfocus</groupId>
                        <artifactId>swagger-ui-dist</artifactId>
                        <version>1.0.0</version>
                        <outputDirectory>${project.build.directory}/swagger-ui</outputDirectory>
                        <excludes>
                            META-INF/resources/webjars/opentext-swagger-ui-dist/2.0.0/opentext-config.js
                        </excludes>
                    </artifactItem>
                </artifactItems>
            </configuration>
        </execution>
    </executions>
</plugin>

Package the war file with the swagger-ui assets and the swagger-ui configuration overide file

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-war-plugin</artifactId>
    <configuration>
        <failOnMissingWebXml>false</failOnMissingWebXml>
        <webResources>
            <resource>
                <!--Include swagger-ui assets-->
                <directory>
                  ${project.build.directory}/swagger-ui/META-INF/resources/webjars/opentext-swagger-ui-dist/2.0.0
                </directory>
                <targetPath>.</targetPath>
            </resource>
            <resource>
                <!--Include opentext-config.js overide file from src/main/html-->
                <directory>src/main/html</directory>
                <targetPath>.</targetPath>
            </resource>
            <resource>
                <!--Include swagger contract-->
                <directory>
                  ${project.build.directory}/swagger-contract/com/hpe/darwin/tag/service/contract
                </directory>
                <targetPath>api-docs</targetPath>
            </resource>
        </webResources>
    </configuration>
</plugin>

Using as an NPM package

This module, opentext-swagger-ui-dist, is a dependency-free module that includes everything required to serve OpenText-branded Swagger UI in a server-side project, or a single-page application that can't resolve npm module dependencies.

npm install git+ssh://git@github.com/MicroFocus/swagger-ui.git#v2.0.0-dist

Or alternatively if you prefer not to use a git url:

npm install https://github.com/MicroFocus/swagger-ui/archive/v2.0.0-dist.tar.gz