swagger是干什么用的（swaggerd）

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。它使得部署管理和使用功能强大的API从未如此简单。Swagger让文件的方法、参数和模型紧密集成到服务器端的代码，允许API始终保持同步。

在软件开发中，常用注解（Annotation）主要用在Java中，并且用于对代码进行标记和说明。下面列举了一些常见的Java注解：

与模型相关的注解：
- ：用于模型类上，对模型类做注释。
- ：用于属性上，对属性做注释。
与接口相关的注解：
- ：用于controller上，对controller进行注释。
- ：用于API方法上，对该API做注释，说明API的作用。
- ：用来包含API的一组参数注解，可以简单的理解为参数注解的集合声明。
- ：用在注解中，也可以单独使用，说明一个请求参数的各个方面。
其他常用注解：
- ：用于属性上、set/get方法上，该属性序列化后可重命名。
- ：用于属性或者方法上，可格式化日期属性的值。
- 注解：使用这个注解可以代替实体类属性的get和set方法。
- 注解：这个接口在编译时会生成相应的实现类。
- ：指定访问方式，如果访问方式不匹配，则无法进行访问。

pom.xml

@Api

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

属性说明valueurl的路径值tags如果设置这个值、value的值会被覆盖produces返回的格式类型例如："application/json, application/xml"consumes接收请求参数的类型例如："application/json, application/xml"protocolsPossible values: http, https, ws, wss.authorizations高级特性认证时配置

案例演示

@ApiOperation

@ApiOperation注解用在方法上，说明方法的作用，每一个url资源的定义。

属性说明valueurl的路径值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"codehttp的状态码默认 200

案例演示

@ApiImplicitParam

@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();
}

@ApiImplicitParams

@ApilmplicitParams 如果有多个参数，则需要使用多个 @ApilmplicitParam 注解来描述，多个 @ApilmplicitParam 注解需要放在一个 @ApilmplicitParams 注解中；

案例演示

@ApiModel和@ApiModelProperty

@ApiModel注解描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用 @ApiImplicitParam注解进行描述的时候；

@ApiModelProperty注解描述一个model的属性。

属性说明value字段说明name参数名称dataType参数类型hidden在文档中隐藏required是否必要example举例说明notes注释说明

案例演示

注意：在这里可以不使用@ApiImplicitParam标注Swagger中的参数信息，因为在这里的输入参数是实体对象，而在实体对象中已经使用@ApiModel和@ApiModelProperty注解进行了标识。

@ApiParam

作用在方法的参数上，用来描述接口的参数信息(一个参设置一个)

必须与、和一起使用。

属性说明name参数名称value参数简单描述defaultValue描述参数默认值required是否为必传参数, false:非必传; true:必传allowMultiple指定参数是否可以通过多次出现来接收多个值hidden隐藏参数列表中的参数example非请求体(body)类型的单个参数示例examples@Example(value = @ExampleProperty(mediaType = “”, value = “”)) 参数示例，仅适用于请求体类型的请求

案例演示

添加以下：

修改application.yml文件，配置项目系统的运行环境（dev/test/prod）

使用maven package打包测试

打开CMD，跳转到target目录，输入命令：java -jar .xxx.jar --spring.profiles.active=prod。可以直接打开jar包修改application.yml配置文件中spring.profiles.active属性切换运行环境，具体请参考以下配置：

开发环境：dev；生产环境：prod；测试环境：test；

swagger是干什么用的（swaggerd）

@Api

@ApiOperation

@ApiImplicitParam

@ApiImplicitParams

@ApiModel和@ApiModelProperty

@ApiParam

相关推荐