一、Swagger简介
Swagger 是最流行的 API 开发工具,它遵循 OpenAPI Specification(OpenAPI 规范,也简称 OAS)。
Swagger 可以贯穿于整个 API 生态,如 API 的设计、编写 API 文档、测试和部署。
Swagger 是一种通用的,和编程语言无关的 API 描述规范。
二、应用场景
- 如果你的 RESTful API 接口都开发完成了,你可以用 Swagger-editor 来编写 API 文档( yaml 文件 或 json 文件),然后通过 Swagger-ui 来渲染该文件,以非常美观的形式将你的 API 文档,展现给你的团队或者客户。
- 如果你的 RESTful API 还未开始,也可以使用 Swagger ,来设计和规范你的 API,以 Annotation (注解)的方式给你的源代码添加额外的数据。这样,Swagger 就可以检测到这些数据,自动生成对应的 API 文档。
三、Swagger工具
Swagger提供了多种工具,帮助解决api的不同的情况下的问题
Swagger-ui 是一套 HTML/CSS/JS 框架,用于渲染 Swagger 文档,以便提供美观的 API 文档界面。也就是说,Swagger-ui 是一个 UI 渲染工具。
三、集成步骤
1、配置Maven依赖
<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、Swagger配置类,还可以统一添加请求头
/**
* Copyright (c) 2016-2019 人人开源 All rights reserved.
*
* https://www.renren.io
*
* 版权所有,侵权必究!
*/
package com.example.demo.config;
import io.swagger.annotations.ApiOperation;
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.ApiKey;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.List;
import static com.google.common.collect.Lists.newArrayList;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
//head请求头参数配置start
ParameterBuilder tokenPar = new ParameterBuilder();
List<Parameter> pars = new ArrayList<Parameter>();
tokenPar.name("x-access-token").description("令牌").modelRef(new
ModelRef("string")).parameterType("header").required(false).build();
pars.add(tokenPar.build());
//head请求头参数配置end
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//加了ApiOperation注解的类,才生成接口文档
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
//包下的类,才生成接口文档
//.apis(RequestHandlerSelectors.basePackage("io.renren.controller"))
.paths(PathSelectors.any())
.build()
.globalOperationParameters(pars) //添加全局head请求头参数配置
.securitySchemes(security()) //添加Authorize配置
.securityContexts(securityContexts()); //添加Authorize配置
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("人人开源")
.description("renren-api文档")
.termsOfServiceUrl("https://www.renren.io")
.version("4.0.0")
.build();
}
/**
* 配置右上角的Authorize
*/
private List<ApiKey> security() {
return newArrayList(
new ApiKey("Authorization", "Authorization", "header"));
}
/**
* 配置右上角的Authorize
*/
private List<SecurityContext> securityContexts() {
return newArrayList(
SecurityContext.builder()
.securityReferences(defaultAuth())
.forPaths(PathSelectors.regex("^(?!auth).*$"))
.build()
);
}
/**
* 配置右上角的Authorize
*/
List<SecurityReference> defaultAuth() {
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
return newArrayList(
new SecurityReference("Authorization", authorizationScopes));
}
}
效果:配置完之后点击右上角的Authorize,弹出认证窗口之后输入请求token,这样之后的每次请求的请求头都会带有token认证信息
3、在Controller中使用Swagger注解
@RestController
@Api(tags="用户管理")
public class UserController {
@GetMapping("/user/list")
@ApiOperation("列表")
@ApiImplicitParams({
@ApiImplicitParam(name = "username", value = "用户名", paramType = "query", required = true, dataType="string"),
@ApiImplicitParam(name = "password", value = "密码", paramType = "query",required = true, dataType="string")
})
public String list(String username,String password)
{
System.out.println(username);
System.out.println(password);
return "success";
}
}
注解说明
- @Api:用在类上,说明该类的作用。
- @ApiOperation:注解来给API增加方法说明。
- @ApiImplicitParams : 用在方法上包含一组参数说明。
- @ApiImplicitParam:用来注解来给方法入参增加说明。
- @ApiResponses:用于表示一组响应
- @ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
- @ApiModel:描述一个Model的信息(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候)
- @ApiModelProperty:描述一个model的属性