springboot配置swagger信息入门2

1.配置swaggerConfig

package com.kuang.config;

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

    //配置Swagger信息 = apiInfo
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact(
                "洋洋",
                "https://www.cnblogs.com/LEPENGYANG/p/15642071.html",
                "319144776@qq.com");
        return new ApiInfo(
                "洋洋的SwaggerAPI文档",
                "即使再小的帆也能远航",
                "v1.0",
                "https://www.cnblogs.com/LEPENGYANG/p/15642071.html",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>());
    }
}

2.swagger配置扫描接口

RequestHandlerSelectors:配置要扫描接口的方式
basePackage:指定扫描的包
any():扫描全部
none():都不扫描
withClassAnnotation:扫描类上的注解，参数是一个注解的反射对象
withMethodAnnotation:扫描方法上的注解
paths:过滤什么路径

//配置了 Swagger 的 docket 的 bean 实例
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()

            //RequestHandlerSelectors:配置要扫描接口的方式
            //basePackage:指定扫描的包
            //any():扫描全部
            //none():都不扫描
            //withClassAnnotation:扫描类上的注解，参数是一个注解的反射对象
            //withMethodAnnotation:扫描方法上的注解
            //paths:过滤什么路径

            .apis(RequestHandlerSelectors.basePackage("com.kuang.controller"))
            //.apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
            //.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
            .paths(PathSelectors.ant("/kuang/**"))
            .build();
}

配置是否启动Swagger

//配置了 Swagger 的 docket 的 bean 实例
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .enable(false) //enable 是否启动Swagger,如果为False,则Swagger 不能在浏览器中访问
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.kuang.controller"))
            .build();
}

3.多配置文件

我们在主配置文件编写的时候，文件名可以是 application-{profile}.properties/yml , 用来指定多个环境版本；

例如：

application-test.properties 代表测试环境配置

application-dev.properties 代表开发环境配置

但是Springboot并不会直接启动这些配置文件，它默认使用application.properties主配置文件；

我们需要通过一个配置来选择需要激活的环境：

4.问题：我只希望我的Swagger在生产环境中使用，在发布的时候不使用？

思路：

• 判断是不是生产环境 flag = false

• 注入enable（flag）

先准备主配置文件 application.properties

spring.profiles.active=pro 
server.port=8080

application-dev.properties

server.port=8081

application-pro.properties

server.port=8082

SwaggerConfig配置文件

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

    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .enable(flag) //enable 是否启动Swagger,如果为False,则Swagger 不能在浏览器中访问
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.kuang.controller"))
            .build();
}

5.配置API文档的分组

配置API文档的分组

.groupName("狂神")

如何配置多个分组

@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");
}

6.swagger的实体类配置

实体类：User

package com.kuang.pojo;

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

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

HelloController类

package com.kuang.controller;

import com.kuang.pojo.User;
import io.swagger.annotations.Api;
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;

@Api(tags = "hello控制类")
@RestController
public class HelloController {
    @GetMapping(value = "/hello")
    public String hello() {
        return "hello";
    }

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

    //Operation接口，不是放在类上的，是方法
    @ApiOperation("hello控制类hello2方法")
    @GetMapping(value = "/hello2")
    public String hello2(@ApiParam("用户名") String username) {
        return "hello" + username;
    }
}

五个注解：

Swagger注解	简单说明
@Api(tags = "xxx模块说明")	作用在模块类上
@ApiOperation("xxx接口说明")	作用在接口方法上
@ApiModel("xxxPOJO说明")	作用在模型类上：如VO、BO
@ApiModelProperty(value = "xxx属性说明",hidden = true)	作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam("xxx参数说明")	作用在参数、方法和字段上，类似@ApiModelProperty

@ApiModel("用户实体类"): 实体类注释，放在实体类上面
@ApiModelProperty("用户名"): 实体类属性注释，放在属性上面
@Api(tags = "hello控制类"): 放在类上面，范围比较大
@ApiOperation("hello控制类hello2方法"): 放在接口或者方法上面：参数注释，放在参数前面
@ApiParam("用户名")：参数注释，放在参数前面

效果：页面上面会有注释

总结：

1. 我们可以通过Swagger给一些比较难理解的属性或者接口，增加注释信息

2.接口文档实时更新

3.可以在线测试