Swagger简单使用

Swagger

• 号称世界上最流行的API框架；
• RestFul Api 文档在线自动生成工具——API文档与API定义同分布更新
• 直接运行，可以在线测试API接口
• 支持多种语言：java/php----

在项目中使用swagger集成springBox：

• swagger2
• swagger ui

在spring boot中集成swagger

（1）新建一个springboot项目——web项目
（2）导入swagger相关依赖

        <!--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>

（3）编写一个controller

package com.example.swaggerdemo.controller;

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @RequestMapping("/hello")
    public String sayHello(){
        return "hello";
    }
}

（4）编写swagger配置类

package com.example.swaggerdemo;

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration //声明是一个配置类
@EnableSwagger2 //开启swagger2
public class SwaggerConfig {
}

（5）测试运行

地址：http://localhost:8080/swagger-ui.html

配置swagger基本信息

package com.example.swaggerdemo;

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

import java.util.ArrayList;

@Configuration //声明是一个配置类
@EnableSwagger2 //开启swagger2
public class SwaggerConfig {

    //配置swagger的docket的Bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    //配置swagger的apiInfo的bean实例
    @Bean
    public ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("able han","https://blog.csdn.net/qq_40179479","1432076549@qq.com");
        return new ApiInfo("Swagger Api文档",
                "han的swagger测试文档",
                "1.0",
                "https://blog.csdn.net/qq_40179479",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<VendorExtension>());
    }
}

Swagger配置扫描接口

   @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())  //配置api基本信息
                .select() //配置扫描
                //apis 扫描符合条件的接口
                  //RequestHandlerSelectors 配置要扫描接口的方式
                        //basePackage:指定要扫描的包
                        //any:扫描全部
                        //none:都不扫描
                        //withClassAnnotation:扫描类上的注解,参数是一个注解的反射对象
                        //withMethodAnnotation:扫描方法上的注解，参数时一个方法上注解的反射对象
                //.apis(RequestHandlerSelectors.any())
                //.apis(RequestHandlerSelectors.none())
                    //.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                .apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
                //paths 扫描路径过滤
                .paths(PathSelectors.any())
                //.paths(PathSelectors.none())
                //.paths(PathSelectors.ant("/example/**"))
                //.paths(PathSelectors.regex(正则表达式))
                .build();
    }

配置是否启动swagger

   //配置swagger的docket的Bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())  //配置api基本信息
                .enable(true); //是否启用swagger
    }

配置swagger Api分组

.groupName("han")

如何配置多个分组文档？配置多个Docket即可。

   //配置swagger的docket的Bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())  //配置api基本信息
                .groupName("han");
    }

    @Bean
    public Docket docket1() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }
    @Bean
    public Docket docket2() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("B");
    }
    @Bean
    public Docket docket3() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("C");
    }

swagger实体类注解

比如当前项目中有这么一个实体：

@AllArgsConstructor
@NoArgsConstructor
@Data
@ApiModel(value = "客户实体类",description = "描述客户基本信息")
public class Customer {
    @ApiModelProperty(value = "客户ID")
    private String id;
    @ApiModelProperty(value = "客户姓名")
    private String name;
    @ApiModelProperty(value = "客户电话")
    private String phone;
}

只要这个实体在请求接口的返回值上（即使是泛型），都能映射到实体项中：

    @GetMapping("/customer")
    public Customer getCustomer(){
        return new Customer("001","客户1","1008611");
    }