Maven
增加 Swagger2 所需依赖,pom.xml
配置如下:
<!-- Swagger2 Begin -->
<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>
<!-- Swagger2 End -->
配置 Swagger2
注意:RequestHandlerSelectors.basePackage("com.xxxx.myshop.service")
为 Controller 包路径,不然生成的文档扫描不到接口
创建一个名为 Swagger2Configuration
的 Java 配置类,代码如下:
package com.funtl.myshop.commons.service.config;
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;
@Configuration
public class Swagger2Configuration {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.xxxx.myshop.service"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("MyShop API 文档")
.description("MyShop API 网关接口,http://www.xxxx.com")
.termsOfServiceUrl("http://www.xxxx.com")
.version("1.0.0")
.build();
}
}
启用 Swagger2
Application 中加上注解 @EnableSwagger2
表示开启 Swagger
package com.funtl.myshop.service.reg;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;
import org.springframework.cloud.stream.annotation.EnableBinding;
import org.springframework.cloud.stream.messaging.Source;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.scheduling.annotation.EnableAsync;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import tk.mybatis.spring.annotation.MapperScan;
@SpringBootApplication
@EnableSwagger2
public class MyShopServiceRegApplication {
public static void main(String[] args) {
SpringApplication.run(MyShopServiceRegApplication.class, args);
}
}
使用 Swagger2
在 Controller 中增加 Swagger2 相关注解,代码如下:
paramType=“header”, header中传入token进行接口验证
paramType=“query”, 正常传参
package com.xh.loanafter.rest.modular.auth.controller;
import com.xh.loanafter.core.exception.GunsException;
import com.xh.loanafter.rest.common.exception.BizExceptionEnum;
import com.xh.loanafter.rest.modular.auth.controller.dto.AuthRequest;
import com.xh.loanafter.rest.modular.auth.controller.dto.AuthResponse;
import com.xh.loanafter.rest.modular.auth.domain.po.TestUser;
import com.xh.loanafter.rest.modular.auth.util.JwtTokenUtil;
import com.xh.loanafter.rest.modular.auth.validator.IReqValidator;
import com.xh.loanafter.rest.modular.auth.validator.impl.DbValidator;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import javax.annotation.Resource;
@ApiOperation(value = "测试接口", notes = "以实体类为参数,单个参数")
@RequestMapping(value = "testApi", method = RequestMethod.POST)
@ApiImplicitParams({
@ApiImplicitParam(paramType = "header", dataType = "String", name = "Authorization", value = "token标记", required = true),
@ApiImplicitParam(paramType = "query", dataType = "String", name = "account", value = "姓名", required = true),
@ApiImplicitParam(paramType = "query", dataType = "String", name = "password", value = "密码", required = true)})
public String testApi(String account,String password) {
TestUser testUser = new TestUser();
testUser.setAccount(account);
testUser.setPassword(password);
return testUser.toString();
}
}
访问 Swagger2
访问地址:http://localhost:8080/swagger-ui.html
@Api:用在请求的类上,表示对类的说明
tags="说明该类的作用,可以在UI界面上看到的注解"
value="该参数没什么意义,在UI界面上也看到,所以不需要配置"
@ApiOperation:用在请求的方法上,说明方法的用途、作用
value="说明方法的用途、作用"
notes="方法的备注说明"
@ApiImplicitParams:用在请求的方法上,表示一组参数说明
@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
name:参数名
value:参数的汉字说明、解释
required:参数是否必须传
paramType:参数放在哪个地方
· header --> 请求参数的获取:@RequestHeader
· query --> 请求参数的获取:@RequestParam
· path(用于restful接口)--> 请求参数的获取:@PathVariable
· body(不常用)
· form(不常用)
dataType:参数类型,默认String,其它值dataType="Integer"
defaultValue:参数的默认值
@ApiResponses:用在请求的方法上,表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
code:数字,例如400
message:信息,例如"请求参数没填好"
response:抛出异常的类
@ApiModel:用于响应类上,表示一个返回响应数据的信息
(这种一般用在post创建的时候,使用@RequestBody这样的场景,
请求参数无法使用@ApiImplicitParam注解进行描述的时候)
@ApiModelProperty:用在属性上,描述响应类的属性
1、@Api:用在请求的类上,说明该类的作用
tags="说明该类的作用"
value="该参数没什么意义,所以不需要配置"
示例:
@Api(tags="APP用户注册Controller")
2、@ApiOperation:用在请求的方法上,说明方法的作用
@ApiOperation:"用在请求的方法上,说明方法的作用"
value="说明方法的作用"
notes="方法的备注说明"
示例:
@ApiOperation(value="用户注册",notes="手机号、密码都是必输项,年龄随边填,但必须是数字")
3、@ApiImplicitParams:用在请求的方法上,包含一组参数说明
@ApiImplicitParams:用在请求的方法上,包含一组参数说明
@ApiImplicitParam:用在 @ApiImplicitParams 注解中,指定一个请求参数的配置信息
name:参数名
value:参数的汉字说明、解释
required:参数是否必须传
paramType:参数放在哪个地方
· header --> 请求参数的获取:@RequestHeader
· query --> 请求参数的获取:@RequestParam
· path(用于restful接口)--> 请求参数的获取:@PathVariable
· body(不常用)
· form(不常用)
dataType:参数类型,默认String,其它值dataType="Integer"
defaultValue:参数的默认值
示列:
-
@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")
-
})
4、@ApiResponses:用于请求的方法上,表示一组响应
@ApiResponses:用于请求的方法上,表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
code:数字,例如400
message:信息,例如"请求参数没填好"
response:抛出异常的类
示例:
-
@ApiOperation(value = "select1请求",notes = "多个参数,多种的查询参数类型")
-
@ApiResponses({
-
@ApiResponse(code=400,message="请求参数没填好"),
-
@ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
-
})
5、@ApiModel:用于响应类上,表示一个返回响应数据的信息
@ApiModel:用于响应类上,表示一个返回响应数据的信息
(这种一般用在post创建的时候,使用@RequestBody这样的场景,
请求参数无法使用@ApiImplicitParam注解进行描述的时候)
@ApiModelProperty:用在属性上,描述响应类的属性
示例:
-
import io.swagger.annotations.ApiModel;
-
import io.swagger.annotations.ApiModelProperty;
-
import java.io.Serializable;
-
@ApiModel(description= "返回响应数据")
-
public class RestMessage implements Serializable{
-
@ApiModelProperty(value = "是否成功")
-
private boolean success=true;
-
@ApiModelProperty(value = "返回对象")
-
private Object data;
-
@ApiModelProperty(value = "错误编号")
-
private Integer errCode;
-
@ApiModelProperty(value = "错误信息")
-
private String message;
-
/* getter/setter */
}
参考文献:https://blog.csdn.net/jiangyu1013/article/details/83107255