springboot学习笔记|番外篇(一):Spring Boot整合Swagger

最新推荐文章于 2022-06-11 23:36:02 发布

程序猿的酒

最新推荐文章于 2022-06-11 23:36:02 发布

阅读量203

点赞数

分类专栏： springboot 文章标签： swagger

本文链接：https://blog.csdn.net/qq_37317845/article/details/97966469

版权

springboot 专栏收录该内容

4 篇文章 0 订阅

订阅专栏

一、Swagger是什么

说得直白点，Swagger就是一款RESTFUL接口文档工具，后端开发人员可用它模拟前端请求，调试程序，前端人员可用它作为接口文档，与后端开发进行交互

二、Swagger配置

本文搭建一个简单的Springboot项目，演示如何在Springboot中集成Swagger

创建Springboot项目
1.创建项目较简单，此处采用idea自带的Spring Initializr创建项目

在这里插入图片描述

引入springboot依赖和Swagger依赖

  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.1.6.RELEASE</version>
    <relativePath/> <!-- lookup parent from repository -->
  </parent>
  <groupId>com.study.swagger</groupId>
  <artifactId>test-swagger</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <name>test-swagger</name>
  <description>Demo project for Spring Boot</description>

  <properties>
    <java.version>1.8</java.version>
  </properties>

  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-test</artifactId>
      <scope>test</scope>
    </dependency>
    
    <!--引入swagger依赖-->
    <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>
  </dependencies>

配置Swagger

@Configuration
public class SwaggerConfig {

  @Bean
  public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .select()
        //此处 basePackage表示项目要使用swagger包路径
        .apis(RequestHandlerSelectors.basePackage("com.study.swagger.testswagger"))
        .paths(PathSelectors.any())
        .build();
  }

  private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
        .title("配置swagger")
        .description("演示swagger如何配置")
        .version("0.0.1")
        .build();
  }
}

启动类开起EnableSwagger注解

@SpringBootApplication
@EnableSwagger2 //开启swagger注解
public class TestSwaggerApplication {

  public static void main(String[] args) {
    SpringApplication.run(TestSwaggerApplication.class, args);
  }

}

创建controller层，此处只为模拟

@RestController
@RequestMapping("/test")
public class TestSwagger {

  @PostMapping(value = "/add")
  public String addUser(@RequestBody
  @ApiParam(name = "用户", value = "传入json格式", required = true)
      User user) {
    return "新增用户:" + user.getUserName();
  }

  @PutMapping(value = "/update")
  public String updateUser(@RequestBody
  @ApiParam(name = "用户", value = "传入json格式", required = true)
      User user) {
    return "更新用户:" + user.getUserName();
  }

}

登录swagger ui查看http://localhost:8081/swagger-ui.html

1.8081:为配置端口
2.显示如下图，则配置swagger配置成功

在这里插入图片描述

三、Swagger注解

1.用于类`@Api`

常用属性说明

value:表示描述信息，当使用tag时，设置的value值将会被覆盖

tags:表示描述信息

用法

由于value值会被tags覆盖，常用tags值即可

@RestController
@RequestMapping("/test"明)
@Api(tags = "测试swagger")
public class TestSwagger {
    
}

2.用于方法

1.@ApiOperation:用于方法整体说明

常用属性说明
- value:描述方法用途
- notes:对方法进行备注说明
- tags:可以将同一个类中方法进行分类展示
- hidden:隐藏方法

用法

@PutMapping(value = "/update/user")
@ApiOperation(value = "更新用户",tags = "用户相关",notes="删除用户",hidden = true)
public String updateUser(){

}
@PutMapping(value = "/add/order")
@ApiOperation(value = "删除用户",tags = "商品相关",notes="增加用户notes")
public String addOrder(){

}

[外链图片转存失败(img-ZNhac9oH-1564650792741)(/home/zycao/.config/Typora/typora-user-images/1564627909789.png)]

2.@ApiImplicitParam && @ApiImplicitParams

用于方法参数设置,主要用于get请求参数配置

@@ApiImplicitParam:表示单个属性

@@ApiImplicitParams:表示多个属性

常用属性说明
- name:设置属性名
- value:属性描述
- defaultValue:默认值
- required:是否必填，默认false
- dataType:表示字段类型,默认String
- paramType:表示请求参数格式
  - body:表示实体
  - path:表示参数在路径上/getUser/api/{id}
  - query:表示get请求参数

用法

@GetMapping("/getUser/{id}")
@ApiImplicitParams({
    @ApiImplicitParam(name = "user_name",value="用户名",required=true),
    @ApiImplicitParam(name = "id")
})
public String getUserByNameAndId(@RequestParam(name="user_name")String userName, Integer id) {
    return userName+":"+id;
}

3.用于属性

@ApiParam():表示接收get请求参数，但实验所得默认为paramType:"body"，而且不能修改，使用@ApiParam()通常与 @RequestParam()配置合使

@ApiModel():主要用于接收对象，用于post请求接收的参数，通常与@RequestBody()配置使用

@ApiModelProperty():主要用于接收对象属性上

@ApiParam用法

@GetMapping("/getUser/{id}")
public String getUserByNameAndId(
    @ApiParam(value = "用户名", required = true)
    @RequestParam(name="user_name")
    String userName,
    @PathVariable(value = "id")
    Integer id) {
    return userName + ":" + id;
}

@ApiModel && @ApiModelProperty()

@ApiModel:通常与@RequestBody配合使用，表示接收实体

@ApiModelProperty:通常与JsonProperty配置使用，可以定义前端传入字段格式为指定格式，通常用于前端格式为下划线到后端驼峰

@Data
@ApiModel
public class User {

  /**年龄*/
  @ApiModelProperty(value = "用户年龄")
  @JsonProperty("age")
  private Integer age;

  /**用户id*/
  @ApiModelProperty(name="user_id",value = "用户id")
  @JsonProperty("user_id")
  private Integer id;

  /**用户名*/
  @ApiModelProperty(value = "用户名")
  @JsonProperty("user_name")
  private String userName;
}

4.Swagger使用

Swagger只是接口文档，它的注解验证只针对Swagger页面请求效，如果要保证通过rest请求后端也能起到验证作用，则需要配合javax.validation.constraints验证使用，现就几种常用业务场景进行介绍

通用设置

@Api(tags="设置对象说明信息")
@RestController
public Class UserController(){
    @ApiOperation(value="设置方法说明信息",tags="设置方法分类展示",notes="设置方法备注信息")
    public String addUser(){

    }    
}

GET请求

通过@ApiImplicitParams配置swagger的参数列表

通过@RequestParam:配置rest请求参数

@ApiOperation(value = "获取用户", tags = "用户相关", notes = "增加用户notes")
@GetMapping(value = "/user/list")
@ApiImplicitParams({
    @ApiImplicitParam(name = "user_name", value = "用户名",required=true),
    @ApiImplicitParam(name = "user_id", value = "用户id",required=true)
})
public String listUser(
    @RequestParam(name="user_id") Integer userId,
    @RequestParam(name="user_name") String userName) {
    return "查询用户id= " + userId + " 的用户"+userName;
}

POST请求

@ApiModel:配置swagger

@ApiModelproperty:配置字段说明信息,required配置默认必填

@JsonProperty:配置序列化字段样式

@NotNull:配置数字不能为空

@NotEmpty:配置字符串不能为空

@Min:表示最小值

要让验证生效，必须增加@Validated注解

@ApiOperation(value = "增加用户", tags = "用户相关", notes = "增加用户notes")
@PostMapping(value = "/add/user")
public String addUser(@RequestBody
    @Validated User user) {
    return "新增用户:" + user.getUserName();
}


@Data
@ApiModel
public class User {

    /**年龄*/
    @ApiModelProperty(value = "用户年龄",required = true)
    @JsonProperty("age")
    private Integer age;

    /**用户id*/
    @ApiModelProperty(name="user_id",value = "用户id",required = true)
    @JsonProperty("user_id")
    @NotNull
    @Min(value = 1)
    private Integer id;

    /**用户名*/
    @ApiModelProperty(value = "用户名",required = true)
    @JsonProperty("user_name")
    @NotEmpty
    private String userName;
}

程序猿的酒

关注

0
点赞
踩
0

收藏

觉得还不错? 一键收藏
0
评论
springboot学习笔记|番外篇(一):Spring Boot整合Swagger

一、Swagger是什么说得直白点，Swagger就是一款RESTFUL接口文档工具，后端开发人员可用它模拟前端请求，调试程序，前端人员可用它作为接口文档，与后端开发进行交互二、Swagger配置本文搭建一个简单的Springboot项目，演示如何在Springboot中集成Swagger创建Springboot项目1.创建项目较简单，此处采用idea自带的Spring Ini...
复制链接

扫一扫