如何为界面生成醒目的文档？

Question

我已经用谷歌搜索过，但是所有有关swagger文档的示例都使用类。我想包括接口，因为读者对API感兴趣，而不对实现感兴趣。

这是我的代码：

包括所需的Maven依赖项：

    <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>

我的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);
    }
}

我的RestController接口

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();
}

和实现

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";
    }
}

全部由必需的swagger配置支持：

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();
  }
}

该代码可作为Maven项目在https://github.com/MKhotele/spring-examples/tree/master/demo获得。

http://localhost:8080/swagger-ui.html显示“ Hello World Controller”；但“ Hello World控制器接口”一无所获。

是否可以使招摇的包含界面？怎么样？

Answer 1

Segii Zhevzhyk在注释中提供了提示。谢谢！

不可能，因此不可能。

OpenAPI specification(formerly Swagger Specification)不仅与REST API的规范有关。这也与他们互动有关。接口从不公开端点以进行交互。但仅是一个实现。

Swagger是围绕OpenAPI构建的一组开源工具可以帮助您设计，构建，记录和消费的规范REST API。

如Introduction to OpenAPI-Specification中所述，

OpenAPI规范（OAS）定义了与语言无关的标准与RESTful API的接口，使人类和计算机都可以无需访问即可发现并了解服务的功能源代码，文档或通过网络流量检查。正确定义后，消费者可以理解并具有最少的实现逻辑。