![80beea47599ea517e49d5e867d858e5c.png](https://i-blog.csdnimg.cn/blog_migrate/870fc977c0104d2d8abe1cc9311168ac.png)
今天在看一只新项目的时候发现酱样
![e0bf17554054b11bed2ce9ffe2810cd8.png](https://i-blog.csdnimg.cn/blog_migrate/5dbd8bc093f319e4927d4e0e7ba766f5.png)
还有酱样
![7097c7c923301f22cbce07471d24f41f.png](https://i-blog.csdnimg.cn/blog_migrate/b9cfd35dab149aa2d021186747135185.png)
这都是啥,好奇心溢出……
Swagger– The World's Most Popular Framework for APIs
Swagger由来和优势
现在多数的项目开发中,网站和移动端都需要进行数据交互和对接,这少不了使用REST编写API接口这种场景。 特别是不同开发小组协作时,就更需要以规范和文档作为标准和协作基础。良好的文档可以减少沟通成本,达到事半功倍的效果。
有时对一些API说明的理解比较模糊,总想着能直接验证一下自己的理解就好了,而不是需要去项目写测试代码来验证自己的想法。 即API文档应具备直接执行能力,这种能力类似word,wiki等是无法提供。 SwaggerUI就是这样一种利器,基于html+javascript实现,倾向于在线文档和测试,使用和集成十分简单,能容易地生成不同模块下的API列表, 每个API接口描述和参数、请求方法都能定制并直接测试得到直观的响应数据。
Swagger缺点
如果是与服务端代码集成,直接嵌入到工程代码中,侵入性比较大,将文档参数和应用参数杂糅在一起,不易阅读,而且比较依赖于项目, 无法独立部署,项目挂掉,文档也无法访问。给后期代码维护增加难度。
如果直接编辑json文档,则难度比较大,即使是官网的在线编辑功能也比较弱,提示功能差劲,很多时候在编辑预览中没问题,导出来部署就显示不正常,而且 不支持多人编辑,只能一次一个人改,部署相当不方便。
用户体验无论请求还是响应无法方便的输入自定义json格式,特别是多层嵌套,异常繁琐。
Swagger常用注解使用工具箱
@Api:用在类上,说明该类的作用。
@ApiOperation:注解来给API增加方法说明。
@ApiImplicitParams : 用在方法上包含一组参数说明。
@ApiImplicitParam:用来注解来给方法入参增加说明。
@ApiResponses:用于表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
code:数字,例如400
message:信息,例如"请求参数没填好"
response:抛出异常的类
@ApiModel:描述一个Model的信息(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候)
@ApiModelProperty:描述一个model的属性
撸它
创建项目就跳过了,文末提供git地址。添加如下项目中必要依赖:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.mybatis.spring.boot</groupId>
<artifactId>mybatis-spring-boot-starter</artifactId>
<version>2.1.0</version>
</dependency>
<dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-java</artifactId>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.springframework.security</groupId>
<artifactId>spring-security-test</artifactId>
<scope>test</scope>
</dependency>
<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>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>1.18.4</version>
</dependency>
<dependency>
<groupId>com.alibaba</groupId>
<artifactId>druid</artifactId>
<version>1.0.24</version>
</dependency>
<dependency>
<groupId>com.alibaba</groupId>
<artifactId>fastjson</artifactId>
<version>1.2.31</version>
</dependency>
创建swagger配置类
@Configuration
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.scg.springbootswaggerui.controller")) //添加需生成文档类所在包路径
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("swagger-ui 测试") //文档标题
.description("swagger-ui 测试") //文档描述
.version("1.0")
.build();
}
}
配置applicatin.yml文件,文件放置在resources文件夹下
server:
port: 8080
spring:
datasource:
driver-class-name: com.mysql.jdbc.Driver
url: jdbc:mysql://localhost:3306/test?useUnicode=true&characterEncoding=UTF-8&useSSL=false #数据库链接填写自己的
username: root #密码和用户名填写自己的
password: root
type: com.alibaba.druid.pool.DruidDataSource
重点来了
@RestController
@Api(value = "LoginController", description = "登陆管理")
@RequestMapping("/demo/LoginController")
@Slf4j
public class LoginController {
@ApiOperation(value = "获取登录时间接口", notes = "获取登录时间接口")
@ApiImplicitParam(name = "user", value = "用户", required = true, dataType = "String",paramType="query") //paramType="query"这个参数很重要参数值不能为path,否则请求参数后台方法接收不到
@RequestMapping(value = "/login.do", method = { RequestMethod.POST,RequestMethod.GET})
public Object login(HttpServletRequest request){
log.info("打印所有参数:"+JSON.toJSONString(request.getParameterMap()));
log.info("登陆用户为:"+request.getParameter("user"));
return new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").format(new Date());
}
}
启动项目的之后输入http://localhost:8080/swagger-ui.html即可访问你的api文档啦!
![111ef0b6353e74ff2cb2a3b014f1b92d.png](https://i-blog.csdnimg.cn/blog_migrate/cba0f98228366fce0e121a5e49604382.jpeg)
可以当做postman来用,填入必要参数访问后台哦~
![b622e0db85cbf6b39a5897e3444c5689.png](https://i-blog.csdnimg.cn/blog_migrate/314447d61aac9d760ed09b018a18daf9.jpeg)
总结:
Swagger-ui优劣参半,好处多多,动态维护文档,方便自己,方便他人使用;缺点就是侵入性
Git地址 https:// github.com/cat-fishing/ springboot-swaggerui.git
![77c83b0ecbbba6536b510eae54670c35.png](https://i-blog.csdnimg.cn/blog_migrate/82c84bf069a21bafd2e262241bac98ac.jpeg)
![3559a3e34f62e4d8efef6594cfc3f784.png](https://i-blog.csdnimg.cn/blog_migrate/566b2eb21e3b1dc91913bdae84fd50df.jpeg)