How to generate swagger documentation for interface?

Question

I have googled it, but all example for swagger documentation are using classes. I would like to include interfaces, as reader is interested in APIs and not implementations.

Here is my code:

Included desired maven dependencies:

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>

My SpringBootApplication:

package com.manojk.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

My RestController interface

package com.manojk.demo;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping(value = "/") // this annotation needed for swagger-ui to work
public interface HelloWorldControllerInterface {
    @GetMapping
    String helloWorld();
}

And implementation

package com.manojk.demo;

import org.springframework.stereotype.Component;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Component // this annotation needed to initialize this controller
public class HelloWorldController implements HelloWorldControllerInterface {
    @Override
    public String helloWorld(){
        return "Hello World";
    }
}

It's all supported by required swagger config:

package com.manojk.demo;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import static springfox.documentation.builders.PathSelectors.regex;

/**
 * Configuration class for Swagger REST API documentation
 *
 */
@Configuration
@EnableSwagger2
/**
 * Run nad hit http://localhost:8080/swagger-ui.html to see it working
 */
public class SwaggerConfig {

  /**
   * @return Swagger Docker
   */
  @Bean
  public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
            .select()
            // .apis(RequestHandlerSelectors.basePackage("com.siemens.oss.domain.controller.service")) # does not work for interfaces
            .apis(RequestHandlerSelectors.basePackage("com.manojk.demo")) // works for implementations
            .paths(regex("/.*"))
            .build();
  }
}

The code is available as maven project at https://github.com/MKhotele/spring-examples/tree/master/demo.

http://localhost:8080/swagger-ui.html shows "Hello World Controller"; but nothing for "Hello World Controller Interface".

Is it possible to make swagger include interface? How?

The controller is the implementation, which is defined by the interface, having two of the same swagger specs would be weird which is why it doesn't generate for both interface and implementation? — Thomas__
Swagger makes it possible to call endpoints and play a bit around. If you add there an interface then this concept will be broken because the interface doesn't define an implementation. If your goal is to provide a sketch/draft of the interface, you can use yaml/json openapi specifications. — Sergii Zhevzhyk
Why do you define @RestController as interface? Has no sense... If you need to implement environment-dependant controllers, use @Profile instead — Valijon

Manojkumar Khotele Manojkumar Khotele · Accepted Answer · 2020-03-14T02:07:12

Hint has been provided in comments by Segii Zhevzhyk. Thanks!

It should not be possible and hence not possible.

OpenAPI specification(formerly Swagger Specification) is not only about specification of REST APIs. It's also about interacting with them. An interface can never expose an endpoint to interact with; but only an implementation.

Swagger is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document and consume REST APIs.

As documented in Introduction to OpenAPI-Specification,

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.

How to generate swagger documentation for interface?

1 Answers