CODEWITHSUNDEEP
spring-bootswaggerswagger-uiswagger-2.0
Manojkumar Khotele
Manojkumar Khotele

Reputation: 1019

How to generate swagger documentation for interface?

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?

Upvotes: 2

Views: 7679

Answers (1)

Manojkumar Khotele
Manojkumar Khotele

Reputation: 1019

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.

Upvotes: 1

Related Questions