是什么
Swagger 是最流行的 API 开发工具,它遵循 OpenAPI Specifification(OpenAPI 规范,也简称 OAS)。Swagger 可以贯穿于整个 API 生态,如 API 的设计、编写 API 文档、测试和部署。 Swagger 是一种通用的,和编程语言无关的 API 描述规范
你可以用 Swagger-editor 来编写 API 文档( yaml 文件 或 json文件),然后通过 Swagger-ui 来渲染该文件,以非常美观的形式将你的 API 文档,展现给你的团队或者客户
如果你的 RESTful API 接口都开发完成了,也可以使用 Swagger ,来设计和规范你的 API,以Annotation (注解)的方式给你的源代码添加额外的数据。这样,Swagger 就可以检测到这些数据,自动生成对应的 API 文档
怎么做
1、改pom
在 supergo_manager_web9001 中添加依赖
<!-- swagger:前端访问的服务,使用swagger生成相应的接口文档说明 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
2、swagger 配置类
package com.supergo.config;
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;
/**
* @Author: xj0927
* @Description: Swagger 文档配置类
* @Date Created in 2020-12-24 17:09
* @Modified By: xj927
*/
@Configuration //注入Spring容器
@EnableSwagger2 //发现swagger
public class SwaggerConfig {
@Bean
public Docket groupRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(groupApiInfo())
//配置分组
.groupName("品牌组")
// 通过.select()方法,去配置扫描接口
.select()
//配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.supergo.controller"))
//筛选显示请求 URL
.paths(PathSelectors.any())
.build();
}
//Api文档信息
private ApiInfo groupApiInfo() {
//联系人方式
Contact contact = new Contact("xj927", "www.baidu.com", "xxx@163.com");
return new ApiInfoBuilder()
.title("swagger文档信息")
.description("swagger_ui_Restful 接口信息")
.contact(contact)
.version("1.0")
.build();
}
}
3、配置接口信息
package com.supergo.controller;
import com.supergo.ApiBrandFeign;
import com.supergo.http.HttpResult;
import com.supergo.pojo.Brand;
import io.swagger.annotations.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
/**
* @Author: xj0927
* @Description: feign服务调用者
* @Date Created in 2020-12-23 22:01
* @Modified By:
*/
@RestController
@RequestMapping("/brand")
//@CrossOrigin //允许访问该controller的请求进行跨域,在zuul网关中全局配置代替
@Api(value = "品牌控制器", protocols = "http", tags = "品牌控制器") //controller类说明
public class BrandController {
@Autowired
private ApiBrandFeign brandFeign;
//品牌分页查询
@ApiOperation(value = "品牌分页查询", notes = "接收分页参数:page,rows") //controller中方法说明
@ApiImplicitParams({ //对方法接收的参数进行说明
//第一个参数
@ApiImplicitParam(paramType = "path", name = "page", value = "第几页", required = true, dataType = "int"),
@ApiImplicitParam(paramType = "path", name = "rows", value = "一页展示多少行", required = true, dataType = "int")
})
@ApiResponses({//响应状态码进行说明
@ApiResponse(code = 200, message = "条件分页查询品牌成功"),
@ApiResponse(code = 500, message = "条件分页查询品牌失败,后台服务出现异常"),
@ApiResponse(code = 401, message = "代表此操作无权访问"),
@ApiResponse(code = 400, message = "表示请求参数错误"),
})
@PostMapping("/query/{page}/{rows}")
public HttpResult getBrandList(@RequestBody Brand brand, @PathVariable Integer page, @PathVariable Integer rows) {
HttpResult result = brandFeign.findPage(brand, page, rows);
return result;
}
//根据主键查询品牌
@ApiOperation(value = "品牌主键查询", notes = "接收查询品牌id参数")
@ApiImplicitParam(paramType = "path", name = "brandId", value = "品牌id", dataType = "Long", required = true)
@ApiResponses({//响应状态码进行说明
@ApiResponse(code = 200, message = "查询品牌成功"),
@ApiResponse(code = 500, message = "条件分页查询品牌失败,后台服务出现异常"),
@ApiResponse(code = 401, message = "代表此操作无权访问"),
@ApiResponse(code = 400, message = "表示请求参数错误"),
})
@GetMapping("/{brandId}")
public HttpResult getBrandById(@PathVariable Long brandId) {
HttpResult result = brandFeign.getBrandById(brandId);
return result;
}
}
4、测试
访问:http://localhost:9001/swagger-ui.html
5、Swagger UI 组件
Swagger 默认提供了 API 展示 UI springfox-swagger-ui ,启动工程后可以访问如下路径查看api信息:
http://localhost:9001/swagger-ui.html
国内还有一个优秀的 Swagger-Bootstrap-UI 基于 Swagger 的前端 UI ,采用 jQuery+bootstrap 实现
Swagger 的默认UI 是上下结构的,用起来不太习惯,所以用 Swagger-Bootstrap-UI 替换 Swagger 默认的 UI 实现 左右菜单风格的 Swagger-UI ,让其看起来更清晰明了
使用方法:
(1)添加依赖
<!--Swagger ui组件:和swagger用的同一套json数据,只是其展示的页面结构更加清晰-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.3</version>
</dependency>
无论是 原生的 Swagger-ui.html 还是 doc.html 页面展示,它们用的 json 数据都是通过 访问 http://localhost:9999/api/v2/api-docs 拿到的,再根据这个数据进行 接口文档的展示
(2)测试使用
访问:
直接访问具体的微服务查看接口文档
再对比一下原生方式: