springboot controller接收参数_Spring Boot中如何使用Swagger构建API文档

Swagger

随着前后端分离架构和微服务架构地流行，我们使用Spring Boot来构建RESTful API项目的场景越来越多，在多人协作的团队中，前后端的沟通成本往往比较大。在这样的背景下，Swagger出现了(当然还有其他的就不一一例举了)。

使用 Swagger 集成文档具有以下几个优势：

• 功能丰富 ：支持多种注解，自动生成接口文档界面，支持在界面测试API接口功能
• 及时更新 ：开发过程中花一点写注释的时间，就可以及时的更新API文档，省心省力
• 整合简单 ：通过添加pom依赖和简单配置，内嵌于应用中就可同时发布API接口文档界面，不需要部署独立服务

开始整合Swagger2

在上一篇的项目基础上，我们来使用一下Swagger。

1. 首先，我们需要在pom.xml中添加依赖,如下:

io.springfox    springfox-swagger2    2.9.2io.springfox    springfox-swagger-ui    2.9.2

2. 接下来我们来编写一个SwaggerConfig配置类
   新建一个包:com.zhlab.demo.config,创建SwaggerConfig类
   SwaggerConfig.java

package com.zhlab.demo.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.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;/** * @ClassName SwaggerConfig * @Description //SwaggerConfig配置类 * @Author singleZhang * @Email 405780096@qq.com * @Date 2020/10/17 0017 上午 11:11 **/@Configuration@EnableSwagger2public class SwaggerConfig {    @Bean    public Docket creatRestApi(){        return new Docket(DocumentationType.SWAGGER_2)                .apiInfo(this.apiInfo())                .select()                //扫描指定路径                .apis(RequestHandlerSelectors.basePackage("com.zhlab.demo.controller"))                // 扫描所有有注解的api，用这种方式更灵活                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))                // 扫描所有                // .apis(RequestHandlerSelectors.any())                .paths(PathSelectors.any())                .build();    }    private ApiInfo apiInfo(){        return new ApiInfoBuilder()                .title("zhLab Demo Api Doc")                .description("api document of zhLab Demo")                .version("1.0.1")                .build();    }}

※说明:

• 在类上，添加 @EnableSwagger2 注解， 标记项目启用 Swagger API 接口文档。
• 通过 createRestApi() 方法，创建 Swagger Docket Bean
• 更多的配置可以在Docket.java、ApiInfo.java两个类的源码中查看

3. 修改上一篇中的HelloController控制器

package com.zhlab.demo.controller;import io.swagger.annotations.ApiOperation;import io.swagger.annotations.ApiParam;import org.springframework.web.bind.annotation.*;/** * @ClassName HelloController * @Description //第一个Springboot接口 * @Author singleZhang * @Email 405780096@qq.com * @Date 2020/10/16 0016 上午 10:55 **/@RestController@RequestMapping("/system/user")public class HelloController {    /* 方法注解 */    @ApiOperation(value = "方法名:打招呼", notes = "打招呼方法的测试")    @GetMapping("/hello")    public String sayHello(/* 参数注解 */ @ApiParam(value = "参数:名字" , required=true ) @RequestParam String name){        return "hi"+name+" ,I can say hello";    }}

启动项目,在浏览器输入http://localhost:8080/swagger-ui.html显示下图:

swagger-ui

执行一下，测试一下接口:

TEST

常用注解说明

swagger 通过注解接口生成文档，包括接口名，请求方法，参数，返回信息等。
@Api: 修饰整个类，用于controller类上
@ApiOperation: 描述一个接口，用户controller方法上
@ApiParam: 单个参数描述
@ApiModel: 用来对象接收参数,即返回对象
@ApiModelProperty: 对象接收参数时，描述对象的字段
@ApiResponse: Http响应其中的描述，在ApiResonse中
@ApiResponses: Http响应所有的描述，用在
@ApiIgnore: 忽略这个API
@ApiError: 发生错误地返回信息
@ApiImplicitParam: 一个请求参数
@ApiImplicitParam: 多个请求参数

总结

以上就是对Swagger的初步体验,前后端分离api文档是节省沟通成本的重要工具，用好它，你肯定会如虎添翼，以后还会推荐YAPI等工具。

项目地址

https://gitee.com/kaixinshow/springboot-note