如何为界面生成swagger文档? [英] How to generate swagger documentation for interface?
问题描述
我已经用谷歌搜索过了，但是所有 swagger 文档的示例都使用了类.我想包括接口，因为读者对 API 而不是实现感兴趣.
这是我的代码:
包含所需的 Maven 依赖项:
<依赖><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></依赖><依赖><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version></依赖>我的 SpringBoot 应用程序:
package com.manojk.demo;导入 org.springframework.boot.SpringApplication;导入 org.springframework.boot.autoconfigure.SpringBootApplication;@SpringBootApplication公共类演示应用{公共静态无效主(字符串 [] args){SpringApplication.run(DemoApplication.class, args);}}我的 RestController 接口
package com.manojk.demo;导入 org.springframework.web.bind.annotation.GetMapping;导入 org.springframework.web.bind.annotation.RequestMapping;导入 org.springframework.web.bind.annotation.RestController;@RestController@RequestMapping(value = "/")//这个注解需要 swagger-ui 工作公共接口 HelloWorldControllerInterface {@GetMapping字符串 helloWorld();}和实施
package com.manojk.demo;导入 org.springframework.stereotype.Component;导入 org.springframework.web.bind.annotation.GetMapping;导入 org.springframework.web.bind.annotation.RequestMapping;导入 org.springframework.web.bind.annotation.RestController;@Component//这个注解需要初始化这个控制器公共类 HelloWorldController 实现 HelloWorldControllerInterface {@覆盖公共字符串 helloWorld(){返回你好世界"；}}这一切都由所需的 swagger 配置支持:
package com.manojk.demo;导入 org.springframework.context.annotation.Bean;导入 org.springframework.context.annotation.Configuration;导入 springfox.documentation.builders.RequestHandlerSelectors;导入 springfox.documentation.spi.DocumentationType;导入 springfox.documentation.spring.web.plugins.Docket;进口 springfox.documentation.swagger2.annotations.EnableSwagger2;导入静态 springfox.documentation.builders.PathSelectors.regex;/*** Swagger REST API 文档的配置类**/@配置@EnableSwagger2/*** 运行 nad hit http://localhost:8080/swagger-ui.html 看看它是否工作*/公共类 SwaggerConfig {/*** @return Swagger Docker*/@豆角，扁豆公共 Docket api() {返回新的 Docket(DocumentationType.SWAGGER_2).选择()//.apis(RequestHandlerSelectors.basePackage("com.siemens.oss.domain.controller.service")) # 不适用于接口.apis(RequestHandlerSelectors.basePackage("com.manojk.demo"))//适用于实现.paths(regex("/.*")).建造();}}代码可作为 maven 项目在 https://github.com/MKhotele/spring-examples/tree/master/demo.
http://localhost:8080/swagger-ui.html 显示Hello World控制器";但Hello World Controller Interface"没有.
是否可以制作 swagger 包含界面?怎么样?
已在评论中提供了提示一>.谢谢！
这应该是不可能的，因此也不可能.
OpenAPI 规范(以前称为 Swagger 规范) 不仅仅是关于 REST API 的规范.这也是关于与他们互动.接口永远不能公开与之交互的端点；但只是一个实现.
<块引用>Swagger 是一组围绕 OpenAPI 构建的开源工具可以帮助您设计、构建、记录和使用的规范REST API.
<块引用>OpenAPI 规范 (OAS) 定义了一种与语言无关的标准RESTful API 的接口，允许人类和计算机无需访问即可发现和了解服务的功能源代码、文档或通过网络流量检查.正确定义后，消费者可以理解并与具有最少实现逻辑的远程服务.
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?
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.
这篇关于如何为界面生成swagger文档?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
