首先, 老规矩, 我们在接触新事物的时候, 要对之前学习和了解过的东西做一个总结.
01
痛 苦
不做, 不行
之前, 前后端分离的系统由前端和后端不同的编写, 我们苦逼的后端工程师会把自己已经写完的 API 接口, 写一个接口文档给到我们前端工程师, 前端工程师拿到接口文档之后, 根据接口文档规定的 URL, 请求方式(POST 或 GET), 请求参数, 返回结果(成功或失败, 失败时, 返回的状态分别代表什么意思), 来对接我们后端提供的 API 接口, 如果提供的接口文档有问题, 那么同样的, 前端对接时, 也会出现问题, 前端会说是后端提供的接口文档的问题, 后端觉得我可能程序更新了, 没有及时更新接口文档. 其实, 不管是前端还是后端, 都希望有一个好的接口文档, 能随着程序的迭代不断更新的接口文档.
而写接口文档这种没有技术含量又苦恼的事儿, 对于后端来说无疑是噩梦一般, API 接口少, 没几个, 可能半个点一个点就完事儿了, 如果 API 接口很多, 比如说整个订单系统的接口, 写接口文档这种事儿可能会耗上一天, 两天, 甚至三天, 最后写完还不一定是对的, 那个痛啊.
02
邂 逅
有痛点, 抛出来
之前写 API 文档的方式各种各样, wiki,Word,Excel,text 等等各种方式, 万物皆可盘.
比如 Word:
对, Word 要把目录给人家定义好, 要不会被喷的.
再比如 Excel:
还有 text:
千篇一律, 能不能再乱一点, 前端已经提这 40 米的大砍刀在向你走来.
有没有自动生成 API 文档的插件呢? 答: 有, 还自带各种插件
关于 SwaggerSwagger 是一个功能强大且易于使用的 API 开发人员工具套件, 适用于团队和个人, 可在整个 API 生命周期 (从设计和文档到测试和部署) 中进行开发.
Swagger 由开放源代码, 免费和市售工具共同组成, 它使任何人 (从技术工程师到街头智能产品经理) 都可以构建每个人都喜欢的惊人 API.
Swagger 由 SmartBear Software 构建, 后者是团队软件质量工具的领导者. SmartBear 落后于软件领域的一些知名公司, 包括 Swagger,SoapUI 和 QAComplete.
在 Swagger 官网上提供了几种工具, 可以通过集成的方式来实现我们想要的效果.
Swagger Inspector: 类似 postman 的一种 API 调试工具, 可以点击 URL, 查看如何使用. https://swagger.io/docs/swagger-inspector/how-to-use-swagger-inspector/.
Swagger Codegen: 是一个开源代码生成器, 可直接从 Swagger 定义的 RESTful API 构建服务器存根和客户端 SDK.Swagger Codegen 的源代码可以在 GitHub 中找到, 点击 URL, 查看如何使用. https://swagger.io/docs/open-source-tools/swagger-codegen/.
Swagger Editor: 是一个开源编辑器, 用于设计, 定义和记录 Swagger 规范中的 RESTful API, 点击 URL 查看如何使用, https://swagger.io/docs/open-source-tools/swagger-editor/
Swagger UI: 提供了一个可视化的 UI 页面展示描述文件. 接口的调用方, 测试, 项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求. 该项目支持在线导入描述文件和本地部署 UI 项目, 点击 URL 查看如何使用, https://swagger.io/docs/open-source-tools/swagger-ui/usage/installation/
03
接 触
收入囊中
Swagger 是什么我们已经介绍完了, 下面我们通过代码示例来讲解如何与 Springboot 结合使用.
1, 引入 Swagger 相关 jar 包(Springboot 相关 jar 自行引入)
- <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>
2, 创建启动类, 设置启动参数, 首先创建一个 class, 命名为 SwaggerApplication, 其中 managerPackage 为 Swagger 要管理的包目录, 比如 com.user.API.controller, 从 header 获取参数名为 Authorization 的值, 可以用于验证权限(如果显示不完整请左右滑动查看全部).
- /**
- * Swagger2 配置类
- * 在与 spring boot 集成时, 放在与 Application.java 同级的目录下.
- * 通过 @Configuration 注解, 让 Spring 来加载该类配置.
- * 再通过 @EnableSwagger2 注解来启用 Swagger2.
- */
- @Configuration
- @EnableSwagger2
- public class SwaggerApplication{
- @Value(value = "${swagger.manager.package}")
- private String managerPackage;
- /**
- * 创建 API 应用
- * apiInfo() 增加 API 相关信息
- * 通过 select()函数返回一个 ApiSelectorBuilder 实例, 用来控制哪些接口暴露给 Swagger 来展现,
- * 本例采用指定扫描的包路径来定义指定要建立 API 的目录.
- *
- * @return
- */
- @Bean
- public Docket createRestApi(){
- ParameterBuilder aParameterBuilder = new ParameterBuilder();
- aParameterBuilder
- .parameterType("header") // 参数类型支持 header, cookie, body, query etc
- .name("Authorization") // 参数名
- .defaultValue("Authorization") // 默认值
- .description("token")
- .modelRef(new ModelRef("string"))// 指定参数值的类型
- .required(false).build(); // 非必需, 这里是全局配置, 然而在登陆的时候是不用验证的
- List<Parameter> aParameters = new ArrayList<Parameter>();
- aParameters.add(aParameterBuilder.build());
- return new Docket(DocumentationType.SWAGGER_2)
- .groupName("v1")
- .select()
- .apis(RequestHandlerSelectors.basePackage(basePackage))
- .paths(PathSelectors.any())
- .build()
- .apiInfo(apiInfo())
- .globalOperationParameters(aParameters);
- }
- public ApiInfo apiInfo(){
- return new ApiInfoBuilder()
- .title("用户管理 API 接口文档")
- .description("用户管理 API 接口文档")
- .termsOfServiceUrl("")
- .contact("sunf")
- .version("1.0")
- .build();
- }
- }
3, 添加实体类引用, PS: 引用只添加 DTO,VO,Entity 不需要, class 头注解 @ApiModel, 申明该类被 Swagger 解析,@ApiModelProperty 声明各字段属性的含义.
- @ApiModel(description = "用户信息")
- @Data
- public class Users {
- @ApiModelProperty(value = "用户 ID")
- private String id;
- @ApiModelProperty(value = "用户姓名")
- private String userName;
- @ApiModelProperty(value = "年龄")
- private String age;
- @ApiModelProperty(value = "性别")
- private String sex;
- @ApiModelProperty(value = "地址")
- private String address;
- @ApiModelProperty(value = "电话")
- private String phone;
- }
4, 声明 Controller, 暴漏 API 接口, 如果一个接口没有声明明确的调用方式(POST 或 GET)method = RequestMethod.POST,Swagger 默认会把所有的调用方式都列出来.
- @RestController
- @RequestMapping("/user")
- @API(value = "用户相关接口",description = "用户信息")
- public class UserController {
- @Autowired
- private UserService userService;
- /**
- * 获取用户详情
- * @param userId
- * @return
- */
- @ApiOperation(value = "获取用户详情", notes = "根据用户 ID 获取用户详情")
- @RequestMapping(value = "/get",method = RequestMethod.POST)
- public Users get(String userId){
- return userService.get(userId);
- }
- /**
- * 获取所有用户
- * @return
- */
- @ApiOperation(value = "获取所有用户", notes = "获取所有用户列表")
- @RequestMapping(value = "/getUserAllList",method = RequestMethod.POST)
- public List<Users> getUserAllList(){
- return userService.getUserAllList();
- }
- }
PS: 未指定访问方式是这样的
5, 到此 Swagger 的配置基本完成, 启动 Springboot 的服务, 访问 Swagger 内置的 web 页面, 可以看到我们暴漏的所有 API 和调用方式, 访问地址: http://localhost:8081/swagger-ui.html
6, 点击获取用户详情的接口, try it out , 可以针对此接口进行访问调试, 点击 Model 可以查看用户实体
7, 如果是页面样式不满意, 我们可以自定义页面样式, 现在 GitHub 已经有道友分享了自定义的 ui, 如何使用请查看, https://github.com/caspar-chen/swagger-ui-layer, 下图是新的 UI, 是不是你的菜.
小结: Swagger, 就是把相关的信息存储在它定义的描述文件里面(YAML 或 JSON 格式), 再通过维护这个描述文件可以去更新接口文档, 以及生成各端代码. 而 Springfox-swagger, 则可以通过扫描代码去生成这个描述文件, 连描述文件都不需要再去维护了. 所有的信息, 都在代码里面了. 代码即接口文档, 接口文档即代码.
来源: https://www.cnblogs.com/onlys/p/11793105.html