Swagger 简介
1, 认识 Swagger
Swagger 是一个规范和完整的框架, 用于生成, 描述, 调用和可视化 RESTful 风格的 web 服务. 总体目标是使客户端和文件系统作为服务器以同样的速度来更新. 文件的方法, 参数和模型紧密集成到服务器端的代码, 允许 API 来始终保持同步.
作用:
接口的文档在线自动生成.
功能测试.
Swagger 是一组开源项目, 其中主要要项目如下:
Swagger-tools: 提供各种与 Swagger 进行集成和交互的工具. 例如模式检验, Swagger 1.2 文档转换成 Swagger 2.0 文档等功能.
Swagger-core: 用于 Java/Scala 的的 Swagger 实现. 与 JAX-RS(Jersey,Resteasy,CXF...),Servlets 和 Play 框架进行集成.
Swagger-JS: 用于 JavaScript 的 Swagger 实现.
Swagger-node-express: Swagger 模块, 用于 node.JS 的 Express Web 应用框架.
Swagger-ui: 一个无依赖的 html,JS 和 CSS 集合, 可以为 Swagger 兼容 API 动态生成优雅文档.
Swagger-codegen: 一个模板驱动引擎, 通过分析用户 Swagger 资源声明以各种语言生成客户端代码.
1 添加依赖
- io.springfox
- springfox-swagger2
- 2.7.0
- io.springfox
- springfox-swagger-ui
- 2.7.0
2 新建一个类配置 Swagger
- import org.springframework.context.annotation.Bean;
- import org.springframework.context.annotation.Configuration;
- import springfox.documentation.builders.ApiInfoBuilder;
- import springfox.documentation.builders.PathSelectors;
- import springfox.documentation.builders.RequestHandlerSelectors;
- import springfox.documentation.service.ApiInfo;
- import springfox.documentation.service.Contact;
- import springfox.documentation.spi.DocumentationType;
- import springfox.documentation.spring.Web.plugins.Docket;
- import springfox.documentation.swagger2.annotations.EnableSwagger2;
- /**
- * Swagger2 的接口配置
- *
- */
- @Configuration
- @EnableSwagger2
- public class SwaggerConfig
- {
- /**
- * 创建 API
- */
- @Bean
- public Docket createRestApi()
- {
- return new Docket(DocumentationType.SWAGGER_2)
- // 详细定制
- .apiInfo(apiInfo())
- .select()
- // 指定当前包路径
- .apis(RequestHandlerSelectors.basePackage("com.bettn"))
- // 扫描所有 .apis(RequestHandlerSelectors.any())
- .paths(PathSelectors.any())
- .build();
- }
- /**
- * 添加摘要信息
- */
- private ApiInfo apiInfo()
- {
- // 用 ApiInfoBuilder 进行定制
- return new ApiInfoBuilder()
- .title("标题: bettn 系统接口文档")
- .description("描述: 用于测试接口")
- .contact(new Contact("hzhh123", null, null))
- .version("0.0.1")
- .build();
- }
- }
3 开启扫描包
- import org.springframework.boot.SpringApplication;
- import org.springframework.boot.autoconfigure.SpringBootApplication;
- import org.springframework.context.annotation.ComponentScan;
- @SpringBootApplication
- @ComponentScan(basePackages={"com"}) //swagger 扫描基类包
- public class BettnAdminApplication {
- public static void main(String[] args) {
- SpringApplication.run(BettnAdminApplication.class, args);
- }
- }
4 写一个类方便访问
- import org.springframework.stereotype.Controller;
- import org.springframework.Web.bind.annotation.RequestMapping;
- import io.swagger.annotations.API;
- @API(value = "swagger 访问页面",description = "swagger 访问页面")
- @Controller
- public class SwaggerController{
- @RequestMapping("/api/swagger")
- public String toSwaggerUI(){
- return "redirect:/swagger-ui.html";
- }
- }
Swagger 的注解说明
@ApiParam(name = 参数, value = 参数说明, required=false|true)
注解写在参数的最左边, 且参数需要使用 @RequestBody,@RequestParam,@PathVariable 参数修饰才起作用
@API(value = 接口类标志, description = 接口类说明)
一般放在类上
@ApiOperation(value = 方法作用名, notes = 方法描述)
修饰方法, 放在方法上
具体参考:
swagger-ui 升级 swagger-Bootstrap-ui 界面好看到起飞
如果项目已经集成了 swagger, 只需要在 pom.xml 添加, 如果你的项目没有集成 swagger, 自行百度或看最下方的链接
swagger-Bootstrap-ui 是 Swagger 的前端 UI 实现, 目的是替换 Swagger 默认的 UI 实现 Swagger-UI, 使文档更友好一点儿....
swagger-Bootstrap-ui? 只是 Swagger 的 UI 实现, 并不是替换 Swagger 功能, 所以后端模块依然是依赖 Swagger 的, 需要配合 Swagger 的注解达到效果
添加依赖
- com.GitHub.xiaoymin
- swagger-Bootstrap-ui
- 1.9.3
最终的依赖
- io.springfox
- springfox-swagger2
- ${swagger.version}
- io.springfox
- springfox-swagger-ui
- ${swagger.version}
- com.GitHub.xiaoymin
- swagger-Bootstrap-ui
- 1.9.3
访问
如 http://localhost:8080/doc.HTML
swagger-Bootstrap-ui 介绍
https://www.oschina.net/p/swagger-bootstrap-ui
码云: https://gitee.com/xiaoym/swagger-bootstrap-ui
GitHub: https://github.com/xiaoymin/Swagger-Bootstrap-UI
在线体验: http://swagger-bootstrap-ui.xiaominfo.com/doc.html
来源: http://www.bubuko.com/infodetail-3057837.html