Swagger
一、swagger是什么？
一款致力于解决接口规范化、标准化、文档化的开源数据库
是一款可以根据resuful风格生成接口开发文档的开源产品
二、seagger怎么使用
1.引入依赖
一：引入Swagger依赖库
<!--引入swagger-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
2.在创建Swagger配置项
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket productApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//为当前包下controller生成API文档
//.apis(RequestHandlerSelectors.basePackage("com.troila"))
//为有@Api注解的Controller生成API文档
//.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
//为有@ApiOperation注解的方法生成API文档
//.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
//为任何接口生成API文档
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //添加ApiOperiation注解的被扫描
.paths(PathSelectors.any())
.build();
//添加登录认证
/*.securitySchemes(securitySchemes())
.securityContexts(securityContexts());*/
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title(”swagger和springBoot整合“).description(”swagger的API文档")
.version("1.0").build();
}
/**
* 配置swagger2的静态资源路径
* @param registry
*/
@Override
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
// 解决静态资源无法访问
registry.addResourceHandler("/**")
.addResourceLocations("classpath:/static/");
// 解决swagger无法访问
registry.addResourceHandler("/swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
// 解决swagger的js文件无法访问
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
/**
* 给API文档接口添加安全认证
*/
/*private List<ApiKey> securitySchemes() {
List<ApiKey> apiKeys = new ArrayList<>();
apiKeys.add(new ApiKey("Authorization", "Authorization", "header"));
return apiKeys;
}
private List<SecurityContext> securityContexts() {
List<SecurityContext> securityContexts = new ArrayList<>();
securityContexts.add(SecurityContext.builder()
.securityReferences(defaultAuth())
.forPaths(PathSelectors.regex("^(?!auth).*$")).build());
return securityContexts;
}
private List<SecurityReference> defaultAuth() {
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
List<SecurityReference> securityReferences = new ArrayList<>();
securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
return securityReferences;
}*/
}
3.基于注解的swagger
（1）在控制层Controller中添加注解来描述接口信息如:
@Api("参数配置")
@Controller
@RequestMapping("/system/config")
public class ConfigController
（2）在方法中配置接口的标题信息
@ApiOperation("查询参数列表")
@ResponseBody
public TableDataInfo list(Config config)
{
startPage();
List<Config> list = configService.selectConfigList(config);
return getDataTable(list);
}
4.API详细说明
| 作用范围 | API | 使用位置 |
|---|---|---|
| 协议集描述 | @Api | 用于controller类上 |
| 对象属性 | @ApiModelProperty | 用在出入参数对象的字段上 |
| 协议描述 | @ApiOperation | 用在controller的方法上 |
| Response集 | @ApiResponses | 用在controller的方法上 |
| Response | @ApiResponse | 用在 @ApiResponses里边 |
| 非对象参数集 | @ApiImplicitParams | 用在controller的方法上 |
| 非对象参数描述 | @ApiImplicitParam | 用在@ApiImplicitParams的方法里边 |
| 描述返回对象的意义 | @ApiModel | 用在返回对象类上 |
1）api标记
用在类上，说明该类的作用。可以标记一个Controller类做为Swagger文档资源，使用方式：
@Api(value = "/user", description = "用户管理")
与Controller注解并列使用。 属性配置：
| 属性名称 | 备注 |
|---|---|
| value | url的路径值 |
| tags | 如果设置这个值、value的值会被覆盖 |
| description | 对api资源的描述 |
| basePath | 基本路径可以不配置 |
| position | 如果配置多个Api 想改变显示的顺序位置 |
| produces | For example, “application/json, application/xml” |
| consumes | For example, “application/json, application/xml” |
| protocols | Possible values: http, https, ws, wss. |
| authorizations | 高级特性认证时配置 |
| hidden | 配置为true 将在文档中隐藏 |
2）ApiOperation标记
用在方法上，说明方法的作用，每一个url资源的定义,使用方式：
@ApiOperation("获取用户信息")
与Controller中的方法并列使用，属性配置：
| 属性名称 | 备注 |
|---|---|
| value | url的路径值 |
| tags | 如果设置这个值、value的值会被覆盖 |
| description | 对api资源的描述 |
| basePath | 基本路径可以不配置 |
| position | 如果配置多个Api 想改变显示的顺序位置 |
| produces | For example, “application/json, application/xml” |
| consumes | For example, “application/json, application/xml” |
| protocols | Possible values: http, https, ws, wss. |
| authorizations | 高级特性认证时配置 |
| hidden | 配置为true将在文档中隐藏 |
| response | 返回的对象 |
| responseContainer | 这些对象是有效的 “List”, “Set” or “Map”.，其他无效 |
| httpMethod | “GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH” |
| code | http的状态码 默认 200 |
| extensions | 扩展属性 |
3）ApiParam标记
请求属性，使用方式：
public TableDataInfo list(@ApiParam(value = "查询用户列表", required = true)User user)
与Controller中的方法并列使用，属性配置：
| 属性名称 | 备注 |
|---|---|
| name | 属性名称 |
| value | 属性值 |
| defaultValue | 默认属性值 |
| allowableValues | 可以不配置 |
| required | 是否属性必填 |
| access | 不过多描述 |
| allowMultiple | 默认为false |
| hidden | 隐藏该属性 |
| example | 举例子 |
@ApiImplicitParams：用在请求的方法上，包含一组参数说明
@ApiImplicitParam：对单个参数的说明
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）--> 请求参数的获取：@PathVariable
· body（请求体）--> @RequestBody User user
· form（普通表单提交）
dataType：参数类型，默认String，其它值dataType="int"
defaultValue：参数的默认值
举例：
@ApiOperation(value="用户登录",notes="随边说点啥")
@ApiImplicitParams({
@ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
@ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
@ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
})
@PostMapping("/login")
public AjaxResult login(@RequestParam String mobile, @RequestParam String password,
@RequestParam Integer age){
//TODO
return AjaxResult.OK();
}
单个参数举例
@ApiOperation("根据部门Id删除")
@ApiImplicitParam(name="depId",value="部门id",required=true,paramType="query")
@GetMapping("/delete")
public AjaxResult delete(String depId) {
//TODO
}
4）ApiResponse标记
响应配置，使用方式：
@ApiResponse(code = 400, message = "查询用户失败")
与Controller中的方法并列使用，属性配置：
| 属性名称 | 备注 |
|---|---|
| code | http的状态码 |
| message | 描述 |
| response | 默认响应类 Void |
| reference | 参考ApiOperation中配置 |
| responseHeaders | 参考 ResponseHeader 属性配置说明 |
| responseContainer | 参考ApiOperation中配置 |
5）ApiResponses标记
响应集配置，使用方式:
@ApiResponses({ @ApiResponse(code = 400, message = "无效的用户") })
与Controller中的方法并列使用，属性配置：
| 属性名称 | 备注 |
|---|---|
| value | 多个ApiResponse配置 |
方法返回值的说明
@ApiResponses：方法返回对象的说明
@ApiResponse：每个参数的说明
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类
举例
@ApiOperation(value = "修改密码", notes = "方法的备注说明，如果有可以写在这里")
@ApiResponses({
@ApiResponse(code = 400, message = "请求参数没填好"),
@ApiResponse(code = 404, message = "请求路径找不到")
})
@PostMapping("/changepass")
public AjaxResult changePassword(@AutosetParam SessionInfo sessionInfo,
@RequestBody @Valid PasswordModel passwordModel) {
//TODO
}
6）ResponseHeader标记
响应头设置，使用方法
@ResponseHeader(name="head",description="响应头设计")
与Controller中的方法并列使用，属性配置：
| 属性名称 | 备注 |
|---|---|
| name | 响应头名称 |
| description | 描述 |
| response | 默认响应类 void |
| responseContainer | 参考ApiOperation中配置 |
7)ApiModel和 ApiModelProperty
@ApiModel：用于JavaBean的类上面，表示此 JavaBean 整体的信息
（这种一般用在post创建的时候，使用 @RequestBody 这样的场景，请求参数无法使用 @ApiImplicitParam 注解进行描述的时候 ）文章来源：https://www.toymoban.com/news/detail-440087.html
@ApiModel("修改密码所需参数封装类")
public class PasswordModel
{
@ApiModelProperty("账户Id")
private String accountId;
//TODO
}
5.浏览API文档
配置好Swagger2并适当添加注解后，启动SpringBoot应用，
访问http://localhost:8080/swagger-ui.html 即可浏览API文档。文章来源地址https://www.toymoban.com/news/detail-440087.html
到了这里，关于Swagger一键式入门使用指南的文章就介绍完了。如果您还想了解更多内容，请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章，希望大家以后多多支持TOY模板网！
