springboot + swagger2的简单使用

最新推荐文章于 2024-07-31 09:32:30 发布

caoweifeng12

最新推荐文章于 2024-07-31 09:32:30 发布

阅读量280

点赞数

分类专栏： spring 文章标签： spring

本文链接：https://blog.csdn.net/caoweifeng12/article/details/105822550

版权

spring 专栏收录该内容

6 篇文章 0 订阅

订阅专栏

Swagger介绍

1.简述

OpenAPI规范（OpenAPI Specification 简称OAS）是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程，
并且已经发布并开源在github上。（https://github.com/OAI/OpenAPI-Specification）
Swagger是全球最大的OpenAPI规范（OAS）API开发工具框架，支持从设计和文档到测试和部署的整个API生命周期的开发。 (https://swagger.io/)
Spring Boot 可以集成Swagger，生成Swagger接口，Spring Boot是Java领域的神器，它是Spring项目下快速构建项目的框架。

1.2Swagger常用注解

在Java类中添加Swagger的注解即可生成Swagger接口，常用Swagger注解如下：

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiModelProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数
@ApiImplicitParam属性：

属性	取值	作用
paramType		查询参数类型
	path	以地址的形式提交数据
	query	直接跟参数完成自动映射赋值
	body	以流的形式提交仅支持POST
	header	参数在request headers 里边提交
	form	以form表单的形式提交仅支持POST
dataType		参数的数据类型只作为标志说明，并没有实际验证
	Long
	String
name		接收参数名
value		接收参数的意义描述
required		参数是否必填
	true	必填
	false	非必填
defaultValue		默认值

springboot + swagger2

创建swagger2的springboot项目

在pom文件里面加上如下依赖

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
  	<version>2.9.2</version>
</dependency>

在项目里面创建一个config包，编写Swagger的配置类,如下图所示

SwaggerConfig配置类内容

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .select()//接口都有哪些东西
                .apis(RequestHandlerSelectors.basePackage("com.apt.springmvcdemo.web.controller"))//controller在哪
                .paths(PathSelectors.any())//所有的路径都生成文档
                //apiInfo就是用来配置网站的基本信息的
                .build().apiInfo(new ApiInfoBuilder()
                        .description("接口文档的描述信息")
                        .title("项目接口文档")
                        //联系人信息
                        .contact(new Contact("javalqg", "http:www.baidu.com", "835185308@qq.com"))
                        .version("v1.0")
                        .license("Apache2.0")
                        .build());
    }
}

这里提供一个配置类，首先通过@EnableSwagger2注解启用Swagger2，然后配置一个Docket Bean，这个Bean中，配置映射路径和要扫描的接口的位置，在apiInfo中，主要配置一下Swagger2文档网站的信息，例如网站的title，网站的描述，联系人的信息，使用的协议等等。
如此，Swagger2就算配置成功了，非常方便。
此时启动项目，输入http://localhost:8080/swagger-ui.html，能够看到如下页面，说明已经配置成功了：

在这里插入图片描述
4. 创建接口

@Api(tags = "用户数据接口")
@RestController
public class UserController {
    @ApiOperation(value = "查询用户",notes = "根据id查询用户")
    @GetMapping("/user") //在restful风格里面要明确指出是get请求还是post请求，不然前端会收到6个方法
    @ApiImplicitParam(name = "id",value = "用户id",required = true,defaultValue = "99")
    public User getUserById(Integer id){
        User user = new User();
        user.setId(id);
        return user;
    }

    @ApiOperation(value = "删除用户",notes = "根据id删除用户")
    @ApiImplicitParam(name = "id",value = "用户id",required = true,defaultValue = "99")
    @ApiResponses({
            @ApiResponse(code = 200,message = "删除成功"),
            @ApiResponse(code = 500,message = "删除失败")
    })
    @DeleteMapping("/user/{id}")
    public void deleteUserById(@PathVariable Integer id){
        System.out.println("deleteUserById:"+id);
    }

    @PutMapping("/user")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id",value = "用户id",required = true,defaultValue = "99"),
            @ApiImplicitParam(name = "username",value = "用户名",required = true,defaultValue = "javalqg")

    })
    @ApiOperation(value = "更新用户",notes = "根据用户id更新用户名")
    @ApiIgnore //生成接口时忽略它
    public User updateUeernameById(String username,Integer id){
        User user = new User();
        user.setId(id);
        user.setUsername(username);
        return user;
    }

    @PostMapping("/user")
    @ApiOperation(value = "添加用户",notes = "添加用户接口")  //@RequestBody:以json的方式来传递参数
    public User addUser(@RequestBody User user){
        return user;
    }
}

这里边涉及到多个API，我来向小伙伴们分别说明：
1. @Api注解可以用来标记当前Controller的功能。
2. @ApiOperation注解用来标记一个方法的作用。
3. @ApiImplicitParam注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入。
4. 如果有多个参数，则需要使用多个@ApiImplicitParam注解来描述，多个@ApiImplicitParam注解需要放在一个@ApiImplicitParams注解中。
5. 需要注意的是，@ApiImplicitParam注解中虽然可以指定参数是必填的，但是却不能代替@RequestParam(required = true)，前者的必填只是在Swagger2框架内必填，抛弃了Swagger2，这个限制就没用了，所以假如开发者需要指定一个参数必填，@RequestParam(required = true)注解还是不能省略。
6. 如果参数是一个对象（例如上文的更新接口），对于参数的描述也可以放在实体类中。例如下面一段代码：

@ApiModel(value = "用户实体类",description = "用户信息描述类")
public class User {
    @ApiModelProperty(value = "用户id")
    private Integer id;
    @ApiModelProperty(value = "用户名")
    private String username;
    @ApiModelProperty(value = "用户地址")
    private String address;
    //省略getter和getter
}

@RestController
@RequestMapping("/user")
@Api(tags = "用户管理相关接口")
public class UserController {

    @Autowired
    private UserService userService;

    @ApiOperation("获取用户列表")
    @RequestMapping(value = "/list")
    public List<UserEntry> findUserList(){
        return userService.findUserList();
    }


    @ApiOperation("新增用户信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "userName",value = "用户名",defaultValue = "zlf"),
            @ApiImplicitParam(name="password",value = "密码",defaultValue = "zlf"),
            @ApiImplicitParam(name = "email",value = "邮箱",defaultValue = "11@qq.com")
    })
    @RequestMapping(value = "/add",method = RequestMethod.GET)
    public String addUser(@RequestParam(value = "userName")String uaserName,@RequestParam(value = "password")String password,@RequestParam(value = "email")String email){
        int falg=userService.addUser(uaserName,password,email);
        if(falg>0){
            return "success";
        }
        return "error";
    }

    @ApiOperation("删除用户信息")
    @ApiImplicitParam(name = "id",value = "1",defaultValue = "1")
    @RequestMapping(value = "/delete",method = RequestMethod.GET)
    public String deleteUser(@RequestParam(value = "id")int id){
        if(userService.deleteUser(id)>0){
            return "success";
        }
        return "error";
    }


    @ApiOperation("获取用户列表2")
    @RequestMapping(value = "/list2",method = RequestMethod.GET)
    public List<UserEntry> findUserList2(){
        return userService.findUserList2();
    }

    @ApiOperation("新增用户信息2")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "userName",value = "用户名",defaultValue = "zlf"),
            @ApiImplicitParam(name="password",value = "密码",defaultValue = "zlf"),
            @ApiImplicitParam(name = "email",value = "邮箱",defaultValue = "11@qq.com")
    })
    @RequestMapping(value = "/add2",method = RequestMethod.GET)
    public String addUser2(@RequestParam(value = "userName")String uaserName,@RequestParam(value = "password")String password,@RequestParam(value = "email")String email){
        int falg= userService.addUser2(uaserName,password,email);
        if(falg>0){
            return "success";
        }
        return "error";
    }

    @ApiOperation("删除用户信息2")
    @ApiImplicitParam(name = "id",value = "1",defaultValue = "1")
    @RequestMapping(value = "/delete2",method = RequestMethod.GET)
    public String deleteUser2(@RequestParam(value = "id")int id){
        if(userService.deleteUser2(id)>0){
            return "success";
        }
        return "error";
    }
}