Springboot 集成 Swagger

Swagger是一个自动生成API文档的框架，避免了传统的手动编写API文档，然后再发给前段的繁琐。

首先：

1、新建一个Sping boot项目，引入以下依赖：

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

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency>

2、Swagger配置类：

@Configuration
@EnableSwagger2
public class Swgger2Configuration {

    @Bean
    public Docket createSwagger2Api(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.cn.spring.cloud.jennire.microservice"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("swagger测试")
                .description("简单容易的API接口文档")
                .version("1.0")
                .build();
    }
}

配置类上需要有@Configuration 和 @EnableSwagger2 注解，需要一个返回Docket的被@Bean注释的方法，名字随意取。

此方法中，new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()) ..... ; apiInfo()方法，执行了Swagger的一些基本信息，这些都是开发人员自己指定；

3、在Application上加EnableSwagger2注解，开启Swagger：

@SpringBootApplication
@EnableSwagger2
public class MicroserviceApplication {

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

4、在接口上加入Swagger：

@RestController
public class HelloController {

    @ApiOperation(value="测试API",notes = "API工具")
    @GetMapping("/hello")
    public String index(@RequestBody User user){

        return "hello";

    }
}

上面的接口有一个User 对象，User对象的参数也可以用Swagger来注释：

@Getter
@Setter
@Builder
@ApiModel(description = "请求参数实体")
public class User implements Serializable {

    @ApiModelProperty(value = "用户名称",required = true)
    private String name;

    @ApiModelProperty(value = "用户性别" ,required = true)
    private String sex;

    @ApiModelProperty(value = "用户年龄",required = true)
    private int age;
}

@Getter 和@Setter 、 @Builder 注解是实现了类中参数的 get set 方法， Builder 是实现了构建器的方式来访问和实例化是对象，只需要引入以下依赖：

<dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.16.20</version>
        </dependency>

接下来启动项目，访问localhost:8080/swagger-ui.html；

Swagger中注解说明：

@Api()：作用于类上，表示这个类是swagger的资源。

tags = ”说明该类的作用“

@ApiOperation()：用在请求的方法上，说明的方法的用户和作用

value=“说明方法的用途、作用”

notes="方法的备注说明“

@ApiImplicitParams()：用在请求的方法上，表示一组参数说明，可以包含多个@ApiImplicitParam()

@ApiImplicitParam()：指定一个请求参数的各个方面

name：参数名

value：参数的汉字说明

required：参数是否必须传

dataType：参数类型

defaultValue：参数的默认值

@ApiResponses()：用在请求的方法上，表示一组响应。可以包含多个@ApiResponse()

@ApiResponse()：用于表示一个错误的响应信息

code：数字

message：信息

response：抛出异常的类

@ApiModel()：用在响应类上，表示一个返回响应数据的信息。

@ApiModelProperty()：用在属性上，描述响应类的属性

Springboot 集成 Swagger

猜你喜欢