swagger2 配置文件，在生产环境将 swagger.enable 设置为 false 即可关闭 swagger
@Configuration
@EnableSwagger2
@ConditionalOnExpression("${swagger.enable: true}")
public class SwaggerConfiguration {
@Value("${swagger.basePackage:'com.magic.platform'}")
private String basePackage;
/**
* buildDocket() 用于创建 Docket 的 Bean，
* buildApiInfo() 创建 Api 的基本信息，用于显示在文档页面上。
* select() 函数返回一个 `ApiSelectorBuilder` 实例，用来控制哪些接口暴露给 Swagger2 来展现。
* 一般采用指定扫描的包路径来定义，本例中 Swagger 会扫描 controller 包下所有定义的API，
* 并产生文档内容（除了被 @ApiIgnore 指定的请求）。
* @return
*/
@Bean
public Docket buildDocket() {
Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(buildApiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage(basePackage))
.paths(PathSelectors.any())
.build();
return docket;
}
private Contact contact() {
return new Contact("GrandKai","https://www.jianshu.com/u/9de0ad0f99bc", "GrandKai@aliyun.com");
}
private ApiInfo buildApiInfo() {
return new ApiInfoBuilder()
.title("Magic Platform APIS")
.description("框架接口信息")
.version("1.0.0")
.contact(contact())
.build();
}
}
依赖配置-特别注意jar包冲突的问题
<swagger.version>2.9.2</swagger.version>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger.version}</version>
<exclusions>
<exclusion>
<groupId>org.springframework</groupId>
<artifactId>spring-beans</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger.version}</version>
</dependency>
...
页面查看接口 http://192.168.4.71:8081/swagger-ui.html
范例
/**
* 根据 refreshToken 刷新 AccessToken
* @param requestModel
* @return
*/
@ApiOperation(value = "刷新 accessToken", notes = "@param refreshToken")
@ApiResponse(code = 200, message = "刷新 AccessToken 成功！")
@PostMapping("refresh/token")
public ResponseModel refreshToken(@RequestBody RequestModel<Void> requestModel) {
Objects.requireNonNull(requestModel, "入参不能为空");
TokenDTO tokenDTO = authenticationService.getRefreshToken(requestModel.getRefreshToken());
return new ResponseModel<>("刷新 AccessToken 成功！", tokenDTO);
}
使用 Spring Security 特别注意，需要将如下 url 加入白名单中，防止访问不到 swagger 接口页面
List<String> swaggerUrls = Arrays.asList("/v2/api-docs", "/csrf", "/**/*swagger*/**", "/error", "/");
参数说明：
说明：
@Api：用在类上，说明该类的作用
@ApiOperation：用在方法上，说明方法的作用
@ApiImplicitParams：用在方法上包含一组参数说明
@ApiImplicitParam：用在 @ApiImplicitParams 注解中，指定一个请求参数的各个方面
paramType：参数放在哪个地方
-header-->请求参数的获取：@RequestHeader
-query-->请求参数的获取：@RequestParam
-path（用于restful接口）-->请求参数的获取：@PathVariable
-body（不常用）
-form（不常用）name：参数名dataType：参数类型required：参数是否必须传value：参数的意思defaultValue：参数的默认值
@ApiResponses：用于表示一组响应
@ApiResponse：用在 @ApiResponses 中，一般用于表达一个错误的响应信息
-
code：数字，例如400 -
message：信息，例如"请求参数没填好" -
response：抛出异常的类
@ApiModel：描述一个Model的信息（这种一般用在 post 创建的时候，使用 @RequestBody 这样的场景，请求参数无法使用 @ApiImplicitParam 注解进行描述的时候）
-
@ApiModelProperty：描述一个model的属性
