????????Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。它使得部署管理和使用功能强大的API从未如此简单。Swagger让文件的方法、参数和模型紧密集成到服务器端的代码,允许API始终保持同步。
在软件开发中,常用注解(Annotation)主要用在Java中,并且用于对代码进行标记和说明。下面列举了一些常见的Java注解:
与模型相关的注解:
@ApiModel
:用于模型类上,对模型类做注释。@ApiModelProperty
:用于属性上,对属性做注释。与接口相关的注解:
@Api
:用于controller上,对controller进行注释。@ApiOperation
:用于API方法上,对该API做注释,说明API的作用。@ApiImplicitParams
:用来包含API的一组参数注解,可以简单的理解为参数注解的集合声明。@ApiImplicitParam
:用在@ApiImplicitParams
注解中,也可以单独使用,说明一个请求参数的各个方面。其他常用注解:
@JsonProperty
:用于属性上、set/get方法上,该属性序列化后可重命名。@JsonFormat
:用于属性或者方法上,可格式化日期属性的值。@Date
注解:使用这个注解可以代替实体类属性的get和set方法。@Mapper
注解:这个接口在编译时会生成相应的实现类。@RequestMapping
:指定访问方式,如果访问方式不匹配,则无法进行访问。pom.xml
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.8.5</version>
</dependency>
<!-- 使用1.5.22-->
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>1.5.22</version>
</dependency>
package com.wfzldr.swagger2;
import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration//和spring boot一起加载
@EnableSwagger2
//@Profile({"dev", "test"}) // dev(开发)、test(测试)、prod(生产)
public class Swagger2Configuration extends WebMvcConfigurationSupport {
/**
* 创建该API的基本信息 http://项目实际地址/doc.html
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 项目名
.title("SpringBoot集成Swagger2")
// 系统的介绍
.description("测试系统")
// 公司的首页等等
.termsOfServiceUrl("https://www.baidu.com")
// sawgger的版本
.version("1.0.0")
.build();
}
/**
* 创建API应用
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// 基于那个包生成文档
.apis(RequestHandlerSelectors.basePackage("com.wfzldr.swagger2.controller"))
.paths(PathSelectors.any())
.build();
}
@Override
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
@Api注解用在类上,说明该类的作用。可以标记一个Controller类做为swagger文档资源。
属性 | 说明 |
---|---|
value | url的路径值 |
tags | 如果设置这个值、value的值会被覆盖 |
produces | 返回的格式类型例如:"application/json, application/xml" |
consumes | 接收请求参数的类型例如:"application/json, application/xml" |
protocols | Possible values: http, https, ws, wss. |
authorizations | 高级特性认证时配置 |
案例演示
@RestController
@RequestMapping("/book")
@Api(value = "书籍管理", tags = "书籍管理")//设置tags这个值、value的值会被覆盖
public class BookController {
}
@ApiOperation注解用在方法上,说明方法的作用,每一个url资源的定义。
属性 | 说明 |
---|---|
value | url的路径值 |
tags | 如果设置这个值、value的值会被覆盖 |
produces | 返回的格式类型例如:"application/json, application/xml" |
consumes | 接收请求参数的类型例如:"application/json, application/xml" |
hidden | 是否在文档中显示 |
notes | 注释说明 |
response | 返回的对象 |
responseContainer | 这些对象是有效的 "List", "Set" or "Map".,其他无效 |
responseReference | 指定对响应类型的引用。指定的引用可以是本地的,也可以是远程的*将按原样使用,并覆盖任何指定的response()类 |
responseHeaders | 响应旁边提供的可能标题列表 |
httpMethod | "GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH" |
code | http的状态码 默认 200 |
案例演示
@GetMapping("/list")
@ApiOperation(value = "查询所有的书籍")
public JsonResponseBody<List<Book>> list() {
...
return JsonResponseBody.success(list);
}
@ApilmplicitParam 注解用来描述一个参数,可以配置参数的中文含义,也可以给参数设置默认值,这样在接口测试的时候可以避免手动输入;
属性 | 说明 |
---|---|
paramType | 参数放在哪个地方 |
name | 参数名称 |
value | 参数代表的含义 |
dataType | 参数类型 |
dataTypeClass | 参数类型 |
required | 是否必要 |
defaultValue | 参数的默认值 |
paramType
类型 | 作用 |
---|---|
path | 以地址的形式提交数据,用于restful接口。请求参数采用@PathVariable获取 |
query | 直接跟参数完成自动映射赋值。请求参数可采用@RequestParam获取 |
body | 以流的形式提交,仅支持POST。请求参数采用@RequestBody获取 |
header | 参数在request headers里边提交。请求参数采用@RequestHeader获取 |
form | 以form表单的形式提交,仅支持POST。 |
案例演示
@ApiOperation(value="查询单个书本信息",notes = "查询单个书本信息") @ApiImplicitParam(value="书本ID",name="bookid",required = true,dataType = "String",defaultValue = "8f46b5018a6811e9a9c528d24413c293" ) @GetMapping("/querySingleBook") public Book querySingleBook(String bookid){ ? ?JsonResponseBody<Book> json = bookService.selectByPrimaryKey(bookid); ? ?return json.getData(); }
@ApilmplicitParams 如果有多个参数,则需要使用多个 @ApilmplicitParam 注解来描述, 多个 @ApilmplicitParam 注解需要放在一个 @ApilmplicitParams 注解中;
案例演示
@GetMapping("/listAndName")
@ApiOperation(value = "模糊查询书籍")
@ApiImplicitParams({
@ApiImplicitParam(name = "name", value = "书本名称", required = true, dataType = "String"),
@ApiImplicitParam(name = "price", value = "书本价格", required = true, dataType = "Double"),
})
public JsonResponseBody<List<Book>> listAndName(@ApiParam(name = "name", value = "书名") String name, double price) {
...
return JsonResponseBody.success(list);
}
@ApiModel注解描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用 @ApiImplicitParam注解进行描述的时候;
@ApiModelProperty注解描述一个model的属性。
属性 | 说明 |
---|---|
value | 字段说明 |
name | 参数名称 |
dataType | 参数类型 |
hidden | 在文档中隐藏 |
required | 是否必要 |
example | 举例说明 |
notes | 注释说明 |
案例演示
@ApiOperation(value="修改书本信息",notes = "修改书本信息")
@PostMapping("/editBook")
public JsonResponseBody<?> editBook(@RequestBody Book book){
? ?return bookService.updateByPrimaryKey(book);
}
注意:在这里可以不使用@ApiImplicitParam标注Swagger中的参数信息,因为在这里的输入参数是实体对象,而在实体对象中已经使用@ApiModel和@ApiModelProperty注解进行了标识。
package com.wfzldr.swagger2.model;
import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import java.io.Serializable;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Getter;
import lombok.Setter;
import lombok.experimental.Accessors;
/**
* <p>
* 书籍表
* </p>
*
* @author wfzldr
* @since 2023-12-19
*/
@Getter
@Setter
@Accessors(chain = true)
@TableName("t_book")
@ApiModel("书籍信息")
public class Book implements Serializable {
private static final long serialVersionUID = 1L;
/**
* 书籍id
*/
@TableId(value = "id", type = IdType.AUTO)
@ApiModelProperty("书籍编号")
private Long id;
/**
* 书名
*/
@TableField("bookname")
@ApiModelProperty("书名")
private String bookname;
/**
* 价格
*/
@TableField("price")
@ApiModelProperty("价格")
private Float price;
/**
* 书籍类型
*/
@TableField("booktype")
@ApiModelProperty(value = "书籍类型")//hidden = true用来隐藏
private String booktype;
}
作用在方法的参数上,用来描述接口的参数信息(一个参设置一个)
@ApiParam
必须与@RequestParam
、@PathVariable
和@RequestHeader
一起使用。
属性 | 说明 |
---|---|
name | 参数名称 |
value | 参数简单描述 |
defaultValue | 描述参数默认值 |
required | 是否为必传参数, false:非必传; true:必传 |
allowMultiple | 指定参数是否可以通过多次出现来接收多个值 |
hidden | 隐藏参数列表中的参数 |
example | 非请求体(body)类型的单个参数示例 |
examples | @Example(value = @ExampleProperty(mediaType = “”, value = “”)) 参数示例,仅适用于请求体类型的请求 |
案例演示
@ApiOperation(value="新增书本信息",notes="新增书本信息")
@PostMapping("/addBooks")
public JsonResponseBody<?> addBooks(
? ? ? ? ? ?@ApiParam(name="bookName",value="bookName",required = true) @RequestParam("bookName") String bookName,
? ? ? ? ? ?@ApiParam(name="price",value="price",required = true) @RequestParam("price") float price,
? ? ? ? ? ?@ApiParam(name="bookType",value="bookType",required = true) @RequestParam("bookType") String bookType){
? ? ?System.out.println("bookName="+bookName+",price="+price+",bookType="+bookType);
? ?return new JsonResponseBody<>();
}
添加以下:
修改application.yml文件,配置项目系统的运行环境(dev/test/prod)
????
spring:
#配置swagger2生产和测试环境不可用
profiles:
active: prod
使用maven package打包测试
打开CMD,跳转到target目录,输入命令:java -jar .\xxx.jar --spring.profiles.active=prod。可以直接打开jar包修改application.yml配置文件中spring.profiles.active属性切换运行环境,具体请参考以下配置:
开发环境:dev; 生产环境:prod; 测试环境:test;
???????