几步操作快速入门swagger

一、前言

• swagger最大的好处就是生成接口文档，并且结合springboot可以通过注解方式快速生成，极大的简化了开发时间，同样也方便前后端联调
• swagger包括三部分: Swagger Editor(基于浏览器的编辑器)，Swagger UI(可以让我们通过浏览器来查看并操作Rest API，Swagger Codegen

二、Swagger接口相关注解说明

1. @Api：可设置对控制器的描述

2. @ApiOperation：: 可设置对接口的描述

3. @ApiIgnore: Swagger 文档不会显示拥有该注解的接口。

4. @ApiImplicitParams: 用于描述接口的非对象参数集。

5. @ApiImplicitParam: 用于描述接口的非对象参数，一般与 @ApiImplicitParams 组合使用。

6. @ApiModel:可设置接口相关实体的描述

7. @ApiModelProperty: 可设置实体属性的相关描述。

三、SpringBoot整合swagger

• 首先pom引入对应的依赖包

<-- swagger依赖包 -->
<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.9.0.RELEASE</version>
</dependency>
<-- lombok依赖包 -->
<dependency>
	<groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>RELEASE</version>
</dependency>
<-- start-web依赖包.... -->

• 简单的主启动类

@SpringBootApplication
public class SwaggerStudyApplication {

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

}

• 定义swagger配置bean

//开启swagger2配置
@Configuration
@EnableSwagger2 
public class SwaggerConfig {

    private static final String NAME = "swagger-study";
	
	//初始化bean
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName(NAME)
                .apiInfo(apiInfo())
                .select()
               .apis(RequestHandlerSelectors.basePackage("com.springboot.study.swagger"))
                .build()
                // devnote 非常重要，正确显示响应
                .genericModelSubstitutes(Callable.class)
                .useDefaultResponseMessages(false);
    }
    
	//对api文档的标题以及基础信息
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title(NAME+"-test")
                .description(NAME)
                .version("1.1.1")
                .build();
    }

}

• 自定义user实体类

@Data
@ApiModel("用户实体类") //对实体类的描述
public class UserBaseInfo {
	//每个变量属性的描述
    @ApiModelProperty(value = "用户名",required = true)
    private String userName;
	
	//每个变量属性的描述
    @ApiModelProperty(value = "用户年龄",required = true)
    private Integer age;

}

• 定义controller

@RestController
@Api(tags = "用户相关接口",description = "提供用户相关api")   //接口集合基本描述
public class UserServiceController {

    //单个接口信息描述
    @ApiOperation("新增用户接口")
    @GetMapping("/insertUser")
    public ResponseResult insertUser(){
        return new ResponseResult(ResponseCodeEnums.SUCCESS);
    }

    @ApiOperation("查询用户接口")
    @GetMapping("/getUser")
    public ResponseResult findUserById(){
        UserBaseInfo userBaseInfo = new UserBaseInfo();
        userBaseInfo.setAge(28);
        userBaseInfo.setUserName("henry");
        return new ResponseResult(ResponseCodeEnums.SUCCESS,userBaseInfo);
    }

    @ApiOperation("删除用户数据接口")
    @PostMapping("/delete")
    public ResponseResult deleteUserById(@RequestBody UserBaseInfo userBaseInfo, Long id){

        return new ResponseResult(ResponseCodeEnums.SUCCESS,id);
    }
}

• 启动springboot项目访问http://ip:port/swagger-ui.html 即可