Swagger2 的简单使用

Swagger的使用

1. 在pom文件中添加Swagger相关依赖

 <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2.swagger的configuration

• spring-boot 使用 @Configuration 的注解进行 往 IOC 容器里加入 bean
• 1. 开启 @EnableSwagger2 注解
  2. 构造出 Docket 以及 API类 就完事了

package tbs.jyy.springbootlearn.configuration;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
            //可以加入多个扫描包,使用 ',' 隔开就可以了
                .apis(RequestHandlerSelectors.basePackage(
                    "tbs.jyy.springbootlearn.controller")
                     )
                .paths(PathSelectors.any())
                .build();
    }


    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("我是标题")
                .description("我是描述信息")
                .contact(new Contact("tbs",null,null))
                .version("1.0")
                .build();
    }
}

3.抒写接口配置注释，这样项目才能扫描到需要展示的接口api来生成文档。下边介绍一下用到的注释。

注解	作用
@Api	修饰整个类，描述Controller的作用
@ApiOperation	描述一个类的一个方法，或者说一个接口
@ApiParam	单个参数描述 (标注在参数上)
@ApiImplicitParams	多个请求参数 (标注在方法上)
@ApiImplicitParam	一个请求参数 (标注在方法上)
@ApiModel	用对象来接收参数(标注在类上的上面)
@ApiProperty	用对象接收参数时，描述对象的一个字段
@ApiResponse	HTTP响应其中1个描述
@ApiResponses	HTTP响应整体描述
@ApiIgnore	使用该注解忽略这个API

代码演示

1. User类

package tbs.jyy.springbootlearn.entities;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import java.io.Serializable;

@Data
@ApiModel("用户的请求")
public class User implements Serializable {

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

    @ApiModelProperty(value = "年龄",example = "3")
    private Integer age;

    public User() {
    }

    public User(String name, Integer age) {
        this.name = name;
        this.age = age;
    }
}

2. HelloController类

package tbs.jyy.springbootlearn.controller;

import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.ModelAttribute;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.annotations.ApiIgnore;
import tbs.jyy.springbootlearn.entities.User;

@RestController
@Api(value = "这是个打招呼的类")
public class HelloController {

    private final static User DEFAULT_USER = new User("TBS",1);     //用来测试的

    @GetMapping("/hello/{name}")
    @ApiOperation("打招呼")
    @ApiResponses({
            @ApiResponse(code = 200, message = "成功")
    })
    public String hello(
            @ApiParam("名字") @PathVariable(required = false) String name
    ) {
        return "hello! Mr." + name;
    }

    @GetMapping("hello2")
    @ApiOperation("第二种打招呼的方式")
    @ApiResponses({
            @ApiResponse(code = 200, message = "成功"),
            @ApiResponse(code = 500, message = "挂掉了")
    })
    public String hello2(
            @ModelAttribute User user
    ) {
        return "Your name are " + user.getName() + ". And your age is " + user.getAge() + ".";
    }

    @GetMapping("ignore")
    @ApiIgnore
    public String ignore(){
        return "这是个被忽略的api";
    }

    @GetMapping("user")
    public User getDefaultUser(){
        return DEFAULT_USER;
    }

}