Swagger

一、简介

可以轻松的整合到Spring Boot中，并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。

文档生成工具，API调试工具

 

二、HelloWorld

1、依赖

<dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-boot-starter</artifactId>
     <version>3.0.0</version>
</dependency>

2、配置Swagger2

package cn.kgc.mybatisplus.config;
​
import lombok.Data;
import lombok.Setter;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.stereotype.Component;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import springfox.documentation.service.Contact;
​
@Configuration
@EnableOpenApi
@ConfigurationProperties("swagger")
@Data
public class SwaggerConfig {
​
    private String basePackage;
    private String title;
    private String description;
    private String terms;
    private String author;
    private String authorUrl;
    private String authorEmail;
    private String version;
​
​
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(
                    RequestHandlerSelectors
                        .basePackage(basePackage)
                )
                .paths(PathSelectors.any())
                .build();
    }
​
    private ApiInfo apiInfo() {
​
        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .termsOfServiceUrl(terms)
                .contact(
                    new Contact(author,authorUrl,authorEmail)
                )
                .version(version)
                .build();
    }
​
}
​

swagger:
  base-package: cn.kgc.mybatisplus.controller
  title: xx项目接口文档
  description: xx项目接口文档描述
  terms: http://ekgc.cn
  version: V1.0
  author: cuiyi
  author-url: cuiyi@zbitedu.cn
  author-email: cuiyi@zbitedu.cn
​
springfox:
  documentation:
    swagger:
      v2:
        use-model-v3: false

3、访问

 localhost:8080/swagger-ui/index.html

不同版本下的Swagger 访问地址不一致， 请核对版本使用

三、常用注解

1、@API

可用在Controller上, 对类进行完整描述， 否则，页面默认显示 类名

@Api(tags = "用户相关API接口")
public class UserController {
}

2、@ApiOperation

 可用在 Controller 方法上， 对方法进行说明

@ApiOperation(value = "条件查询用户信息")
public R<List<User>> list(User user){
    return R.success(userService.list());
}

3、@ApiParam

用于方法参数上， 指明方法参数作用

@GetMapping("/{id}")
@ApiOperation(value = "根据id查询用户信息")
public R detail(@ApiParam("用户id") @PathVariable("id")Integer id){
    return R.success("成功");
}

4、@ApiImplicitParams

配合 @ApiImplicitParam 用于方法上，表示一组参数说明。

对于int/Integer类型的参数， example 属性必须提供， 否则后台会出现 NumberFormatExcepction

 

5、@ApiModel

配和 @ApiModelProperty 用于 对象类型参数所属类上。用于解释对象以及类的作用

 

@Data
@EqualsAndHashCode(callSuper = false)
@TableName("t_user")
@ApiModel("用户信息")
public class User implements Serializable {
    private static final long serialVersionUID = 1L;
​
    @TableId(value = "id", type = IdType.AUTO)
    @ApiModelProperty(hidden = true)
    private Integer id;
​
    @TableField("cardNo")
    @ApiModelProperty(value = "银行卡号",example = "111",
                      required = true)
    private String cardno;
​
    @ApiModelProperty(value = "密码")
    private String password;
}

 

四、完整版