Swagger的使用

目录

 

swagger是一个可以生成RESTful风格的接口文档、支持在线调试的文档框架。

接口指的是后台暴露给前端访问的地址，一个服务、模块暴露出来给其他服务、模块调用的地址，是controller上映射的url。

 

原生swagger的使用

依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>

swagger的ui有很多种，常见的如下，根据自己的审美添加其中一种即可

<!-- swagger-bootstrap-ui，访问 /doc.html -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

<!-- swagger-ui，官方提供的ui，访问 /swagger-ui.html -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>

<!-- swagger-ui-layer，访问 /docs.html -->
<dependency>
    <groupId>com.github.caspar-chen</groupId>
    <artifactId>swagger-ui-layer</artifactId>
    <version>1.1.3</version>
</dependency>

<!-- swagger-mg-ui，访问 /document.html -->
<dependency>
    <groupId>com.zyplayer</groupId>
    <artifactId>swagger-mg-ui</artifactId>
    <version>1.0.6</version>
</dependency>

 
配置类 config.SwaggerConfig

/**
 * Swagger配置
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("xm商城接口文档")  //文档标题
                .description("2020.07.01更新")  //文档描述
                .termsOfServiceUrl("")
                .version("1.0")  //版本
                .build();
    }


    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())  //设置ApiInfo
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.chy.mall.controller"))  //指定要扫描Swagger注解的基本包，指定controller即可，会自动扫描相关的实体类
                .paths(PathSelectors.any())
                .build();
    }

}

 

Swagger注解使用示例

实体类

@Data
@ApiModel("用户信息")
public class User {

    @ApiModelProperty("用户id")
    private Integer id;

    @ApiModelProperty("用户名")
    private String username;

    @ApiModelProperty("密码")
    private String password;

    @ApiModelProperty("手机号")
    private String tel;

    @ApiModelProperty("住址")
    private String address;

}

 

controller

/**
 * 对用户的操作
 */
@RestController
@RequestMapping("/user")
@Slf4j
@Api(value = "user-api", tags = "用户接口")   //value一般取类名去掉Controller后的camel写法，加上-api
public class UserController {

    /**
     * 根据用户id查询用户信息
     */
    @GetMapping("/info/{id}")
    @ApiOperation(value = "查询用户信息", notes = "根据用户id查询用户信息")  //value是简述，notes是补充、说明
    @ApiImplicitParam(name = "id", value = "用户id", dataType = "int", paramType = "path", required = true)
    public User findUserById(@PathVariable Integer id) {
        User user = new User();
        user.setId(id);
        return user;
    }


    /**
     * 注册
     */
    @PostMapping("/register")
    @ApiOperation(value = "注册", notes = "此接口用于处理前端提交的注册表单")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用户名", dataType = "string", paramType = "form", required = true),
            @ApiImplicitParam(name = "password", value = "密码", dataType = "string", paramType = "form", required = true),
            @ApiImplicitParam(name = "tel", value = "手机号", dataType = "string", paramType = "form"),
            @ApiImplicitParam(name = "address", value = "住址", dataType = "string", paramType = "form")
    })
    public String register(@ApiIgnore User user) {  //@ApiIgnore 忽略此参数，使用实体类接收时，尽量重新使用@ApiImplicitParam表名参数
        log.info("用户信息：{}", user);
        return "注册成功";
    }


    /**
     * 登录
     */
    @PostMapping("/login")
    @ApiOperation(value = "登录", notes = "此接口用于处理前端提交的登录表单")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用户名", dataType = "string", paramType = "form", required = true),
            @ApiImplicitParam(name = "password", value = "密码", dataType = "string", paramType = "form", required = true),
    })
    public String login(String username, String password) {
        log.info("用户名：{}，密码：{}", username, password);
        return "登录成功";
    }


}

 

Swagger常用注解

@Api
用在controller上，描述该controller
 

@ApiOperation
用在方法上，描述该方法
 

@ApiImplicitParams
用在方法上，用于包含一组@ApiImplicitParam（参数说明）
 

@ApiImplicitParam
描述形参，一个@ApiImplicitParam描述一个形参。只有一个时可以直接放在方法上，有多个时需放在@ApiImplicitParams中。常用属性如下

属性	说明
name	参数名
value	描述信息
dataType	该参数的数据类型，和mybatis的别名差不多，可以小写
paramType	传参方式
required	是否必需，布尔型，默认false 不是必需的。和@RequestParam的required不同，@ApiImplicitParam的required只是在swagger文档中显示是否必需、在swagger中调试时检测参数是否为空
defaultValue	默认值

 
paramType 可选的值如下

可选的值	说明
path	通过url中restful方式传递参数
query	通过url中的?xxx=xxx&xxx=xxx方式传递参数
form	通过表单传递参数
header	通过请求头传递参数
body	通过请求体传递参数

 

@ApiIgnore
可标注在类上、方法上、形参表的参数类型前，被@ApiIgnore 修饰的部分不会被提取到接口文档中。

此注解常用于修饰未写好的类、方法，以及自动传入的参数，eg. request、response对象。