正文

SpringBoot 集成 Swageer2

IP云
IP云V管理员/2 阅读
09/03
小程序：扫一扫查出行
【扫一扫了解最新限行尾号】
复制小程序

添加Maven依赖

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>

添加配置类

package com.erp.server.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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;@EnableSwagger2
@Configuration
public class SwaggerConfig { @Bean
public Docket creatRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.erp.server.controller"))
.paths(PathSelectors.any())
.build();
} private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("进销存系统")
.description("这里是进销存系统的后台接口文档")
//服务条款网址
.termsOfServiceUrl("http://localhost:8080/swagger-ui.html")
//联系人
.contact(new Contact("wangbo","url地址", "email地址"))
.version("1.0")
.build();
}}

注解使用

@Api

用在请求类上，说明该类的作用。可以标记一个Controller类做为swagger文档资源。

value：url的路径值，在UI界面上也看到，可以不用配置。

String value() default "";

tags：说明该类的作用，可以在UI界面上看到的内容

String[] tags() default {""};

produces：配置返回数据类型，例如application/json，application/xml等

String produces() default "";

consumes：配置请求头，例如application/json，application/xml等

String protocols() default "";

authorizations：高级特性认证时配置

Authorization[] authorizations() default {@Authorization("")};

hidden：默认为false，配置为true将在文档中隐藏

boolean hidden() default false;

@ApiOperation

用在请求的方法上，说明方法的用途、作用

value：说明方法的用途、作用

String value();

notes：方法的备注说明

String notes() default "";

tags：

String[] tags() default {""};

response：返回的对象

Class<?> response() default Void.class;

responseContainer：这些对象是有效的List，Set，Map，其他是无效的

String responseContainer() default "";

responseReference：

String responseReference() default "";

httpMethod：可以配置其中HTTP请求方式

String httpMethod() default "";

nickname：

String nickname() default "";

produces：配置返回数据类型，例如application/json，application/xml等

String produces() default "";

consumes：配置请求头，例如application/json，application/xml等

String consumes() default "";

protocols：

String protocols() default "";

authorizations：高级特性认证时配置

Authorization[] authorizations() default {@Authorization("")};

hidden：默认为false，配置为true将在文档中隐藏

boolean hidden() default false;

responseHeaders：配置响应头

ResponseHeader[] responseHeaders() default {@ResponseHeader(
name = "",
response = Void.class
)};

code：HTTP的状态码，默认200

int code() default 200;

extensions：扩展属性

Extension[] extensions() default {@Extension(
properties = {@ExtensionProperty(
name = "",
value = ""
)}
)};

@ApiImplicitParams

用在请求的方法上，表示一组参数说明，里面通过ApiImplicitParam配置具体参数。

public @interface ApiImplicitParams {
ApiImplicitParam[] value();
}

@ApiImplicitParam

用在请求的方法上，表示单个参数说明；或者用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

name：参数名

String name() default "";

value：参数说明解释

String value() default "";

defaultValue：参数的默认值

String defaultValue() default "";

allowableValues：

String allowableValues() default "";

required：参数是否必传 true | false，默认false

boolean required() default false;

access：

String access() default "";

allowMultiple：

boolean allowMultiple() default false;

dataType：参数类型，默认String，只作为标志说明，不做实际验证，String和Long

String dataType() default "";

dataTypeClass：

Class<?> dataTypeClass() default Void.class;

paramType：查询参数位置

header：请求参数放置于 Header，使用@RequestHeader获取

query：请求参数放置于请求地址后边，使用@RequestParam获取

path：请求参数放置于请求地址路径中，使用@PathVariable获取

body：以流的形式提交参数，仅支持POST

form：以form表单的形式提交参数，仅支持POST

String paramType() default "";

example：

String example() default "";

examples：

Example examples() default @Example({@ExampleProperty(
mediaType = "",
value = ""
)});

type：

String type() default "";

format：

String format() default "";

allowEmptyValue：

boolean allowEmptyValue() default false;

readOnly：

boolean readOnly() default false;

collectionFormat：

String collectionFormat() default "";

@ApiParam

public @interface ApiParam {
String name() default ""; String value() default ""; String defaultValue() default ""; String allowableValues() default ""; boolean required() default false; String access() default ""; boolean allowMultiple() default false; boolean hidden() default false; String example() default ""; Example examples() default @Example({@ExampleProperty(
mediaType = "",
value = ""
)}); String type() default ""; String format() default ""; boolean allowEmptyValue() default false; boolean readOnly() default false; String collectionFormat() default "";
}

@ApiModel

一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候，用于对类进行说明，描述一个Model的信息，表示参数用实体类接收。

public @interface ApiModel {
String value() default ""; String description() default ""; Class<?> parent() default Void.class; String discriminator() default ""; Class<?>[] subTypes() default {}; String reference() default "";
}

@ApiModelProperty

注解用于方法、字段，表示对model属性的说明或者数据操作更改，配合ApiModel一起使用。

public @interface ApiModelProperty {
String value() default ""; String name() default ""; String allowableValues() default ""; String access() default ""; String notes() default ""; String dataType() default ""; boolean required() default false; int position() default 0; boolean hidden() default false; String example() default ""; boolean readOnly() default false; String reference() default ""; boolean allowEmptyValue() default false;
}

@ApiResponses

用在请求的方法上，表示一组响应

public @interface ApiResponses {
ApiResponse[] value();
}

@ApiResponse

用在@ApiResponses中，一般用于表达一个错误的响应信息

public @interface ApiResponse {
int code(); String message(); Class<?> response() default Void.class; String reference() default ""; ResponseHeader[] responseHeaders() default {@ResponseHeader(
name = "",
response = Void.class
)}; String responseContainer() default "";
}

@ApiIgnore

用在Controller类或者接口方法上，表示该类或者接口被忽略，不在接口文档显示

public @interface ApiIgnore {
//简要说明为何忽略此参数/操作
String value() default "";
}

问题

目前了解到的是Swagger不支持直接获取JSONObject和Map类型的参数，这种参数内部字段不可知，文档显示不出来

如果不想封装为一个Model的话可以参考下面的博客实现下，自定义一个注解。

https://blog.csdn.net/cy921107/article/details/82761575 JSONObject

https://blog.csdn.net/hellopeng1/article/details/82227942 Map

示例

package com.erp.server.controller;import com.alibaba.fastjson.JSONObject;
import com.erp.server.model.User;
import com.erp.server.service.TestService;
import com.erp.server.utils.Constants;
import com.erp.server.utils.result.ResultBuilder;
import com.erp.server.utils.result.StatusCode;
import io.swagger.annotations.*;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;@Api(tags = {"测试接口类"})
@RestController
@RequestMapping(value = "/api/test")
public class TestController { private static final Logger logger = LoggerFactory.getLogger(TestController.class); @Autowired
private TestService testService;
@ApiIgnore
@ApiOperation(value = "测试Hello", notes = "一个测试的hello接口")
@GetMapping("/hello")
public String hello(){
return "Hello Spring Boot";
} @ApiOperation(value = "查询用户", notes = "根据ID查询用户")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, paramType = "path", dataType = "integer")
@GetMapping("/user/{id}")
public ResultBuilder<User> user(@PathVariable("id")Integer id){
User user = testService.getUserById(id);
return new ResultBuilder<User>(user, StatusCode.SUCCESS);
} @ApiOperation(value = "查询用户", notes = "根据ID和姓名查询用户")
@ApiImplicitParams({
@ApiImplicitParam(name = "token", value = "用户凭证", required = true, paramType = "header", dataType = "String"),
@ApiImplicitParam(name = "id", value = "用户ID", required = true, paramType = "query", dataType = "integer"),
@ApiImplicitParam(name = "name", value = "用户名", required = true, paramType = "query", dataType = "String")
})
@GetMapping("/user/id/name")
public ResultBuilder<User> user1(@RequestHeader("token")String token,
@RequestParam("id")Integer id,
@RequestParam("name")String name){
logger.debug("token:{},id：{},name：{}", token, id, name);
User user = testService.getUserById(id);
return new ResultBuilder<User>(user, StatusCode.SUCCESS);
} @ApiOperation(value = "添加用户", notes = "使用JSON数据添加用户")
@ApiImplicitParam(name = "jsonObject", value = "用户数据", required = true, paramType = "body",
examples = @Example(value = @ExampleProperty(mediaType = "application/json", value = "{'id':'','name':'','age':''}"))
)
@PostMapping("/user/add/")
public ResultBuilder<User> adduser(@RequestBody JSONObject jsonObject){
logger.debug(jsonObject.toJSONString());
Integer id = jsonObject.getInteger("id");
User user = testService.getUserById(id);
return new ResultBuilder<User>(user, StatusCode.SUCCESS);
} @ApiOperation(value = "添加用户", notes = "使用对象数据添加用户")
@ApiImplicitParam(name = "user", value = "用户数据", required = true, paramType = "body", dataType = "User")
@PostMapping("/user/add1/")
public ResultBuilder<User> adduser1(@RequestHeader(Constants.ACCEPT_VERSION)String acceptVersion,
@RequestBody User user){
return new ResultBuilder<User>(null, StatusCode.SUCCESS);
}}

@Api 使用示例

属性注释

@Api使用在接口类上

tags说明该类的作用，可以在UI界面上看到的内容

示例代码

@Api(tags = {"版本接口类"})
@RestController
@RequestMapping("/api/version")
public class VersionController {
......
}

界面显示

@ApiOperation 和 @ApiImplicitParam 使用示例

属性注释

@ApiOperation使用在接口方法上

value接口名

notes接口注释米描述

@ApiImplicitParams表示多个参数的情况，需@ApiImplicitParam配合使用

@ApiImplicitParam表示单个参数

name参数

value参数描述

required参数是否必须，默认false

dataType参数类型，这个一般还是别写了，经常写了导致无法使用

paramType参数位置

header：请求参数放置于 Header，使用@RequestHeader获取

query：请求参数放置于请求地址后边，使用@RequestParam获取

path：请求参数放置于请求地址路径中，使用@PathVariable获取

body：以流的形式提交参数，仅支持POST

form：以form表单的形式提交参数，仅支持POST

示例代码

@ApiOperation(value = "采购单列表", notes = "用于查询采购单列表")
@ApiImplicitParams({
@ApiImplicitParam(name = "pageNum", value = "查询的页码，默认1", required = false, paramType = "query"),
@ApiImplicitParam(name = "pageSize", value = "每页显示条数，默认10", required = false, paramType = "query"),
@ApiImplicitParam(name = "wareId", value = "采购ID", required = false, paramType = "query"),
@ApiImplicitParam(name = "startTime", value = "开始时间，毫秒数", required = false, paramType = "query"),
@ApiImplicitParam(name = "endTime", value = "结束时间，毫秒数", required = false, paramType = "query"),
@ApiImplicitParam(name = "wareStatus", value = "采购单状态。-1：删除，0：正常", required = false, paramType = "query"),
@ApiImplicitParam(name = "wareType", value = "采购类型：0：入库单，1：退货单", required = false, paramType = "query")
})
@GetMapping("/list")
public ResultBuilder getWareHouseList(@RequestHeader(Constants.VERSION_CODE)Integer versionCode,
@RequestHeader(Constants.ACCESS_TOKEN)String token,
@RequestParam(value = "pageNum", required = false)Integer pageNum,
@RequestParam(value = "pageSize", required = false)Integer pageSize,
@RequestParam(value = "wareId", required = false)String wareId,
@RequestParam(value = "startTime", required = false)Long startTime,
@RequestParam(value = "endTime", required = false)Long endTime,
@RequestParam(value = "wareStatus", required = false)Integer wareStatus,
@RequestParam(value = "wareType", required = false)Integer wareType){
return wareHouseService.getWareHouseList(pageNum, pageSize, wareId, startTime, endTime, wareStatus, wareType);
}

界面显示

@ApiModel 和 @ApiModelProperty 使用示例

属性注释

@ApiModel 使用在实体类上

value实体类名称

description实体类描述信息

@ApiModelProperty 使用在实体类中字段上

value字段名

required字段是否必须，默认false

hide字段是否隐藏，默认false

example字段值示例

示例代码

实体类

@ApiModel(value = "软件版本", description = "这里是描述信息")
public class Version {
@ApiModelProperty(value = "版本", required = true, example = "1.0.0")
private String version;
@ApiModelProperty(value = "版本号", required = true)
private Integer versionCode;
@ApiModelProperty(value = "最小版本号", required = true)
private Integer minVersionCode;
@ApiModelProperty(value = "强制更新标志", required = true)
private Integer updateForce;
@ApiModelProperty(value = "更新内容")
private String updateContent;
@ApiModelProperty(value = "更新地址", required = true)
private String updateUrl;
@ApiModelProperty(hidden = true)
private Date createTime;
@ApiModelProperty(hidden = true)
private Date updateTime;
省略set/get
}

接口方法

@ApiOperation(value = "新版本检查", notes = "检查APP是否需要进行版本升级")
@PostMapping("/check")
public ResultBuilder versionCheck(@RequestBody Version version){
。。。
}

界面显示

Models中也会显示这个Model