SpringBoot整合Swagger-ui快速生成在线API文档

Posted 天乔巴夏丶

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了SpringBoot整合Swagger-ui快速生成在线API文档相关的知识,希望对你有一定的参考价值。

SpringBoot整合Swagger-ui实现在线API文档

Swagger是一款功能强大的api框架,支持在线接口文档的ui界面,还提供了在线测试功能,此外,它还支持流行的Restful风格接口。

本篇要点

  • 简单介绍restful风格。

  • 介绍SpringBoot与Swagger-ui快速整合。

  • 介绍Swagger-ui常用注解。

一、restful风格简单介绍

REST(Representational State Transfer):表述性状态传递,它是一种针对网络应用的设计和开发方式,可以降低开发的复杂性,提高系统的可伸缩性。

简单来说,HTTP协议本身是无状态的协议,客户端想要操作服务器,可以通过请求资源的方式,将"状态"进行传递。

  • GET请求表示获取资源。
  • POST请求表示新建资源。
  • PUT请求表示更新资源。
  • DELETE请求表示删除资源。

二、SpringBoot与Swagger-ui快速整合

1、第一种方式:使用官方依赖

一、导入依赖

        <properties>
        <swagger.version>2.9.2</swagger.version>
    	</properties> 

        <!--swagger2官方依赖-->
		<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>

二、编写Swagger的配置文件

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .pathMapping("/")
                .select()
           		 //为当前包下controller生成API文档
                .apis(RequestHandlerSelectors.basePackage("com.hyh.fireworks.web"))
                // 为有@Api注解的Controller生成API文档
                //.apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) 
                // 为有@ApiOperation注解的方法生成API文档
                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger接口文档")
                .description("Fireworks 博客网站 接口文档 ")
                .contact(new Contact("天乔巴夏", "https://www.hyhwky.com", "1332790762@qq.com"))
                .version("1.0")
                .build();
    }
}

三、在实体类model上应用注解

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value = "User对象", description = "用户表")
public class User implements Serializable {

    private static final long serialVersionUID = 1L;

    @ApiModelProperty(value = "id")
    private Integer id;

    @ApiModelProperty(value = "用户名")
    private String name;

    @ApiModelProperty(value = "年龄")
    private Integer age;
}

四、在接口上应用注解

注:以下注解不加也是可以测试成功的,不过为了文档的可读性,建议加上方法注释。

@Api(tags = "User控制器") //修饰整个类,描述Controller的作用
@RestController
@RequestMapping("/users")
public class UserController {

    private static final List<User> USERS = new ArrayList<>();

    static {
        USERS.add(new User(1,"hyh",12));
        USERS.add(new User(2,"summer day",18));
        USERS.add(new User(3,"天乔巴夏",20));
    }

    @GetMapping("/{id}")
    @ApiOperation("获取指定user")
    public User getUser(@PathVariable @ApiParam(value = "id",required = true,defaultValue = "3") Integer id){
        return USERS.get(id - 1);
    }

    @DeleteMapping("/{id}")
    @ApiOperation("删除指定user")
    @ApiImplicitParam(name = "id", value = "user id", required = true, dataType = "Integer",paramType = "path")
    public String deleteUser(@PathVariable Integer id){
        USERS.remove(id - 1);
        return "success";
    }

    @PostMapping()
    @ApiOperation("新增用户")
    public String postUser(@RequestBody User user){
        USERS.add(user);
        return "success";
    }

    @PutMapping("/{id}")
    @ApiOperation("更新用户")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "id", required = true, dataType = "Integer",paramType = "path"),
            @ApiImplicitParam(name = "user", value = "user 实体", required = true, dataType = "User")
    })
    public String putUser(@PathVariable Integer id , @RequestBody User user){
        user.setId(id);
        USERS.set(id - 1,user);
        return "success";
    }

    @GetMapping()
    @ApiOperation("用户列表")
    public List<User> getUsers(){
        return USERS;
    }

    @ApiIgnore //生成接口文档时,忽略该接口
    @GetMapping("/ignore")
    public String ignoreTest(){
        return "ignore";
    }
}

五、访问http://localhost:8081/swagger-ui.html即可看到效果

2、第二种方式:使用第三方依赖

文档及源码地址:https://github.com/SpringForAll/spring-boot-starter-swagger,内有详细文档说明,利用Spring Boot的自动化配置特性来实现快速的将swagger2引入spring boot应用来生成API文档,简化原生使用swagger2的整合代码。

感兴趣的小伙伴可以照着文档上的demo自己测试一下哈。

三、swagger-ui的基本注解

  • @Api:用于修饰Controller
  • @ApiOperation:用于修饰Controller类中的方法
  • @ApiParam:用于修饰接口中的参数
  • @ApiModelProperty:用于修饰实体类的属性

源码下载

本文内容均为对优秀博客及官方文档总结而得,原文地址均已在文中参考阅读处标注。最后,文中的代码样例已经全部上传至Gitee:https://gitee.com/tqbx/springboot-samples-learn,另有其他SpringBoot的整合哦。

参考阅读

以上是关于SpringBoot整合Swagger-ui快速生成在线API文档的主要内容,如果未能解决你的问题,请参考以下文章

SpringBoot学习—— springboot快速整合swagger文档

Spring boot整合Swagger

SpringBoot/Git/Linux/EasyCode

Swagger-UI

SpringBoot/Git/Linux/EasyCode

springBoot整合swagger常见问题一