Spring Boot整合Swagger

  • A+
所属分类:Java片段

Swagger优势

spring-boot作为当前最为流行的Java web开发脚手架,越来越多的开发者选择用其来构建企业级的RESTFul API接口。这些接口不但会服务于传统的web端(b/s),也会服务于移动端。在实际开发过程中,这些接口还要提供给开发测试进行相关的白盒测试,那么势必存在如何在多人协作中共享和及时更新API开发接口文档的问题。

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

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

整合Swagger

在pom文件中添加swagger依赖

<!--整合swagger-->
<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>

创建swagger配置类

/**
 * @Description TODO
 * 微信公众号:云说Java、Java栈记
 * @Date 2021/3/3 22:15
 * @Created by 墨云
 */
/**
 * @Description TODO
 * 微信公众号:云说Java、Java栈记
 * @Date 2021/3/3 22:15
 * @Created by 墨云
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //配置controller的扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.kjyfx.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        ApiInfo apiInfo = new ApiInfoBuilder().title("SpringBoot整合Swagger")
                .description("SpringBoot整合Swagger的描述信息...")
                .license("前往墨云个人博客")
                .licenseUrl("https://www.kjyfx.com")
                .contact(new Contact("墨云", "https://www.kjyfx.com", "123455655@qq.com"))
                .version("1.0")
                .build();
        return apiInfo;
    }
}

如果项目中有配置拦截器,还需要在拦截器中对swagger资源进行放行

//放行swagger
registration.excludePathPatterns("/swagger-ui.html");
registration.excludePathPatterns("/swagger-resources/**");
registration.excludePathPatterns("/error");
registration.excludePathPatterns("/webjars/**");

常用注解

swagger 通过注解接口生成文档,包括接口名,请求方法,参数,返回信息等。

@Api: 修饰整个类,用于controller类上

@ApiOperation: 描述一个接口,用户controller方法上

@ApiParam: 单个参数描述

@ApiModel: 用来对象接收参数,即返回对象

@ApiModelProperty: 对象接收参数时,描述对象的字段

@ApiResponse: Http响应其中的描述,在ApiResonse中

@ApiResponses: Http响应所有的描述,用在

@ApiIgnore: 忽略这个API

@ApiError: 发生错误的返回信息

@ApiImplicitParam: 一个请求参数

@ApiImplicitParams: 多个请求参数

@RestController
@RequestMapping("/sysUser")
@Api(description = "系统用户控制类")
public class SysUserController {

    @Autowired
    private SysUserService userService;

    @GetMapping("/getUserById")
    @ApiOperation(value = "通过id获取用户信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户id", defaultValue = "1",required = true),
    })
    public BaseResponse getUserById(Long id){
        SysUser user = userService.getById(id);
        return BaseResponse.renderSuccess("成功!",user);
    }

}

在浏览器中输入http://localhost:9000/base/swagger-ui.html

访问swagger接口文档成功

Spring Boot整合Swagger

  • 云说Java
  • 关注公众号获取更多资源
  • weinxin
  • Java栈记
  • 关注公众号获取更多资源
  • weinxin
墨云

发表评论

:?: :razz: :sad: :evil: :!: :smile: :oops: :grin: :eek: :shock: :???: :cool: :lol: :mad: :twisted: :roll: :wink: :idea: :arrow: :neutral: :cry: :mrgreen: