在SpringBoot中Swagger配置及使用

Swagger号称世界上最流行的Api框架,它是RestFul 风格的Api。文档在线自动生成工具：Api文档与API定义同步更新。可以直接运行，能在线测试API接口；支持多种编程语言：（Java、PHP等）。

官网：https://swagger.io/

在项目中使用Swagger需要配置springbox

SpringBoot集成Swagger

1.新建一个springboot的web项目

2.导入swagger相关依赖

                <!--swagger-->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.9.2</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.9.2</version>
		</dependency>                

3.编写一个简单项目工程

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

@RestController
public class HelloController {

    @RequestMapping(value = "/hello")
    public String hello(){
        return "hello word";
    }
}

4.创建一个config，新建一个SwaggerConfig配置swagger

@Configuration//配置类，加上就能配置到配置里面
@EnableSwagger2//开启Swagger2
public class SwaggerConfig {
    
}

5.测试swagger是否能使用

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

配置swagger

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.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 {
    //配置了swaggerDocket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    //配置swagger信息apiInfo
    private ApiInfo apiInfo(){

        //作者信息
        Contact DEFAULT_CONTACT = new Contact("ljj", "https://www.cnblogs.com/jjsir/", "[e-mail]");

        return new ApiInfo(
                "ljj  SwaggerAPI文档",
                "学海无涯苦作舟",
                "1.0",
                "https://www.cnblogs.com/jjsir/",
                DEFAULT_CONTACT,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

swagger配置扫描接口

    //配置了swaggerDocket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //RequestHandlerSelectors配置扫描接口方式
                //.basePackage("com.ljj.controller");指定要扫描的包
                //.any();全部扫描
                //.none();全不扫描
                //.withClassAnnotation(RestController.class);扫描类上的注解，参数是一个注解的反射对象
                //.withMethodAnnotation(GetMapping.class);扫描方法上的注解
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ljj.swagger.controller"))
                //.paths()过滤什么路经
                .paths(PathSelectors.any())
                .build();
    }

在.select()上方配置.enable(false) 可以判断是否启动swagger 为false则不启动。
可以给swagger设置在开发环境中使用，部署环境中不使用

    //配置了swaggerDocket的bean实例
    @Bean
    public Docket docket(Environment environment){
        //设置要显示的swagger环境
        Profiles profiles = Profiles.of("dev", "test");
        //通过environment.acceptsProfiles 判断是否处在自己设定环境中
        boolean b = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(b)  //是否启动swagger   当前是"dev", "test"环境就为true 否则为false则不启动 
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ljj.swagger.controller"))
                .paths(PathSelectors.any())
                .build();
    }

使用.groupName("swagger学习")  对swagger分组进行自定义命名

配置API文档的分组

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

使用多个@Bean可以swagger分组

实体类配置

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

//@Api (注释)
@ApiModel(value = "user实体类")
public class User {
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;
}

controller

import com.ljj.swagger.pojo.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class UserController{

    @GetMapping(value = "/helloWord")
    public String helloWord(){
        return "hello word";
    }

    //只要我们接口中返回值存在实体类，他就会被扫描到swagger中
    @PostMapping("/user")
    public User user(){
        return new User();
    }

    //Operation接口 不是放类上面的，他是方法
    @ApiOperation("hello控制类")
    @PostMapping("/select")
    public String select(@ApiParam("用户名") String username){
        return "hello"+username;
    }

    @ApiOperation("Post测试类")
    @PostMapping("/selectUser")
    public User selectUser(User user){
        return user;
    }
}

结束语

我们可以通过swagger把比较难理解的属性和接口添加注释，方便和前端对接，而且swagger可以及时更新、在线测试。

注意点：出于安全考虑，和节省内存   正式上线时请关闭swagger！！！

 

来源地址：狂神说  https://www.bilibili.com/video/BV1Y441197Lw?p=4