# demo-swagger

**Repository Path**: cugjack/demo-swagger

## Basic Information

- **Project Name**: demo-swagger
- **Description**: Springboot中配置swagger的测试demo
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2023-05-14
- **Last Updated**: 2023-05-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: demo

## README

# Springboot集成Swagger
## 依赖
```
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
    <exclusions>
        <exclusion>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
        </exclusion>
    </exclusions>
</dependency>

<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-models</artifactId>
    <version>1.5.22</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
```
## 异常：
1.
> Exception encountered during context initialization - cancelling refresh attempt: org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

这是由于 Springboot超过了2.6版本，切换成2.5即可
2.
> java.lang.NumberFormatException: For input string: ""
at java.lang.NumberFormatException.forInputString(NumberFormatException.java:65) ~[na:1.8.0_191]
at java.lang.Long.parseLong(Long.java:601) ~[na:1.8.0_191]
at java.lang.Long.valueOf(Long.java:803) ~[na:1.8.0_191]
at io.swagger.models.parameters.AbstractSerializableParameter.getExample(AbstractSerializableParameter.java:412) ~[swagger-models-1.5.20.jar:1.5.20]

这是因为对于使用了注解`@ApiModelProperty`的字段来说，默认是需要给一个`example`的，不然启动时会报错，但是不影响运行

参考文章：
[解决swagger的类型转换报错问题](https://blog.csdn.net/woliuqiangdong/article/details/121295320)
[Swagger的NumberFormatException异常最简单的解决方案](https://blog.csdn.net/Tony_wang000/article/details/105287715)
## 注解

### @APi
该注解作用于`controller`类上，用于标识此`controller`类的含义
如`@Api(tags = "人物类接口")`
![](./images/QQ截图20230511195356.png)
![](./images/QQ截图20230511195434.png)

### @ApiOperation
该注解作用于方法上，默认属性为`value`，也有其他属性如`note`
如：`@ApiOperation(value = "查询ID对应的人物", notes = "根据id查询人物")`
value的内容写在外面，note的内容写在里面，可以很长，一般只用value即可
![](./images/QQ截图20230511200037.png)
### @ApiModel
该注解作用于实体类上，属性有`value`, `description`等，一般不需要，默认就是类名
### @ApiModelProperty
作用于字段上，一般和`@ApiModel`同时使用，用来描述字段，其属性有`value`, `name`等，一般也只用这两个，默认为`value`属性，所以要写描述，得在`value`中写
```java
@ApiModel
public class Person {
    @ApiModelProperty("ID")
    private Integer id;
    @ApiModelProperty(value = "name", name = "姓名")
    private String name;
    private LocalDateTime birthDay;

}
```
![](./images/QQ截图20230511201059.png)
### @ApiParam
该注解作用于请求参数上，属性有`value`,`name`,`defaultValue`,`required`等
> 注意，name不要轻易使用，会影响参数的输入，最好是不用

```java
@GetMapping("/list/{id}")
@ApiOperation(value = "查询ID对应的人物", notes = "根据id查询人物")
public List<Person> list(@ApiParam(name = "任务id", value = "ID", defaultValue = "0", required = true) @PathVariable Integer id) {
    log.info("id:{}", id);
    return new ArrayList<>();
}
```
请求结果
![](./images/QQ截图20230511202414.png)
![](./images/QQ截图20230511202510.png)
这里明显是将name的值作为参数传递了，所以报错，一般可以不使用这个注解，只需要在`@RequestParam`里面写好就行了