@[toc]
简介
优点
后端根据 swagger 语法, 自动生成漂亮规范的接口文档.
做交互测试.
劣势
侵入式的, 影响程序运行, 尤其是传参的时候.
注意
swagger 分 1.2 版本和 2.0 版本, 差异较大. swagger1.2 即 swagger-ui ; swagger2.0 即 springfox-swagger . 本文介绍的使用方式是新的版本, 即 springfox-swagger .
发布生产, 关闭 swagger, 以防泄漏项目接口文档, 被 ***
引入 swagger 组件
pom.xml 中加入
- <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>
代码实战
我看很多博主说 swagger 的配置代码要和项目启动文件在同级目录, 即如下
但是, 移入 config 目录下, 经过测试, 也是正常的, 那这样就看个人习惯了.
DemoApplication.java
- package com.example;
- 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.spi.DocumentationType;
- import springfox.documentation.spring.web.plugins.Docket;
- import springfox.documentation.swagger2.annotations.EnableSwagger2;
- // 通过 @Configuration 注解, 让 Spring 来加载该类配置.
- // 再通过 @EnableSwagger2 注解来启用 Swagger2.
- @Configuration
- @EnableSwagger2
- public class DemoSwagger {
- @Bean
- public Docket API() {
- return new Docket(DocumentationType.SWAGGER_2)
- .apiInfo(apiInfo())
- .select()
- // 指定要扫描的包路径
- .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
- .paths(PathSelectors.any())
- .build();
- }
- private ApiInfo apiInfo() {
- return new ApiInfoBuilder()
- .title("项目 api 文档")
- .description("swagger 接入教程")
- .version("1.0")
- .build();
- }
- }
因为之前已经配置好了 spring security, 所以浏览器网址中输入 http://localhost:8080/swagger-ui.html 后, 会被拦截住, 输入之前配置好的用户密码后, 效果如下所示;
因为之前测试用户登录, 用户权限, 所以 controller 里面已经有了一些接口方法, 但是就让它这样默认, 显然用户体验不好, 所以在之前的 userController 里继续加上 swagger 的注解.
@API: 用在类上, 说明该类的作用.
@ApiOperation: 说明该方法的作用.
具体而更细致的注解参见官方文档 常用注解说明 .
UserController.java
- package com.example.controller;
- import io.swagger.annotations.API;
- import io.swagger.annotations.ApiOperation;
- import org.springframework.stereotype.Controller;
- import org.springframework.Web.bind.annotation.RequestMapping;
- import org.springframework.Web.bind.annotation.RequestMethod;
- import org.springframework.Web.bind.annotation.ResponseBody;
- @Controller
- @RequestMapping("user")
- @API(value = "用户模块说明", description = "提供用户的增, 删, 改, 查")
- public class UserController {
- @RequestMapping(value = "/addUser", method = RequestMethod.GET)
- @ResponseBody
- @ApiOperation(value = "添加用户", notes = "放一些信息, 供测试判断")
- String addUser() {
- return "这是添加用户!!!";
- }
- @RequestMapping(value = "/deleteUser", method = RequestMethod.POST)
- @ResponseBody
- @ApiOperation(value = "删除用户", notes = "放一些信息, 供测试判断")
- String deleteUser() {
- return "这是删除用户!!!";
- }
- @RequestMapping("/updateUser")
- @ResponseBody
- @ApiOperation(value = "修改用户", notes = "放一些信息, 供测试判断")
- String updateUser() {
- return "这是修改用户!!!";
- }
- @RequestMapping(value = "/findAllUsers", method = RequestMethod.PUT)
- @ResponseBody
- @ApiOperation(value = "查询用户", notes = "放一些信息, 供测试判断")
- String findAllUsers() {
- return "这是查询用户!!!";
- }
- }
效果图如下
具体打开某一条, 如下
很明显, 有了中文注释, 文档可读性更强.
要说明的是, 平时写 @RequestMapping 注解的时候, 我通常会简写, 如上 demo 中的修改用户方法. 但是 swagger 是侵入式的, 如果未指定 RequestMethod 类型, 就会把一大堆都列出来, 如 GET,HEAD,POST,PUT,DELETE,OPTIONS,PATCH , 而其他指定好的, 则是一条.
来源: http://www.bubuko.com/infodetail-3297948.html