SpringBoot中配置Swagger

撒子是Swagger？

• 使用swagger可以帮助我们更简单的API接口的开发
• API文档与API定义同步更新，可以在线测试API接口（API接口就是controller的requestmapping）

Swagger其实就是我们前后端分离时来实现前后端开发的信息及时更新Api的一个框架，是前后端的唯一联系。比如我们后端写了一些controller接口，前端就能通过访问swagger-ui来及时的查看到。

 

Swagger的页面主要有四个部分：

• Swagger信息：开发者的一些信息什么的。
• 接口信息：我们后端写的controller接口的信息。
• 实体类信息：就是实体类信息啦，不过只有在controller中返回值有实体类的才会有显示。
• 分组：对应着一个个的Docket。

 

• 

 

Swagger的使用

1、新建一个SpringBoot-web项目

2、导入相关依赖

    io.springfox
    springfox-swagger2
    2.9.2


    io.springfox
    springfox-swagger-ui
    2.9.2

3、配置Swagger

在SwaggerConfig中配置Swagger的基本信息：

​
package com.lyr.swagger.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;

import static springfox.documentation.service.ApiInfo.DEFAULT_CONTACT;

@Configuration
@EnableSwagger2   //开启Swagger2
public class SwaggerConfig {
    //配置了Swagger的Docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    //配置Swagger信息
    private ApiInfo apiInfo(){
        Contact contact = new Contact("lyr", "https://blog.csdn.net/wan_ide", "[email protected]");
        return new ApiInfo(
                "Lyr's Api Documentation",
                "面朝大海，然后春暖花开",
                "1.0",
                "https://blog.csdn.net/wan_ide",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

​

效果：

 

Swagger配置扫描接口

RequestHandlerSelectors 配置要扫描接口的方式：

• basePackage：指定要扫描的包
• any()：描述全部
• none()：不扫描
• withClassAnnotation：扫描类上的注解，参数是一个注解的反射对象
• withMethodAnnotation：描述方法的注解

 

package com.lyr.swagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import org.springframework.web.bind.annotation.RequestMapping;
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;

import java.util.ArrayList;

import static springfox.documentation.service.ApiInfo.DEFAULT_CONTACT;

@Configuration
@EnableSwagger2   //开启Swagger2
public class SwaggerConfig {
    //配置了Swagger的Docket的bean实例
    @Bean
    public Docket docket(Environment environment){

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //.enable(false)  是否启动Swagger
                .enable(flag)
                .select()
                //RequestHandlerSelectors 配置要扫描接口的方式
                //basePackage：指定要扫描的包
                //any()：描述全部
                //none()：不扫描
                //withClassAnnotation：扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotation：描述方法的注解
                //.apis(RequestHandlerSelectors.withMethodAnnotation(RequestMapping.class))
                .apis(RequestHandlerSelectors.basePackage("com.lyr.swagger.controller"))
                //paths() 过滤扫描路径
                //.paths(PathSelectors.ant("/lyr/**"))
                .build();
    }
}

 

使Swagger在生产环境中使用，在发布时不使用

1、新建一个application-dev.properties，生产环境时的配置，设置端口号为8081

2、新建一个application-pro.properties，发布环境时的配置，设置端口号为8082

3、在application.properties中激活生产环境时的配置：

spring.profiles.active=pro

在SwaggerConfig中配置根据环境启动Swagger：

package com.lyr.swagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import org.springframework.web.bind.annotation.RequestMapping;
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;

import java.util.ArrayList;

import static springfox.documentation.service.ApiInfo.DEFAULT_CONTACT;

@Configuration
@EnableSwagger2   //开启Swagger2
public class SwaggerConfig {
    //配置了Swagger的Docket的bean实例
    @Bean
    public Docket docket(Environment environment){
        //设置要显示的Swagger环境
        Profiles profiles = Profiles.of("pro");
        //通过environment.acceptsProfiles判断是否处在自己设定的环境当中
        boolean flag = environment.acceptsProfiles(profiles);


        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.lyr.swagger.controller"))
                .build();
    }
}

效果：

当生产时（激活dev）可以访问，当发布时（激活pro）不可以访问​​​​​​​

 

配置API文档的分组：

.groupName("lyr")

配置多个分组就new多个Docket。

 

Swagger中的注解

• @ApiModel("用户实体类")：给Models加上注释，用在实体类上。但是要求返回值中存在实体类，才会被扫描到。
• @ApiModelProperty("用户名")：给实体类中的属性加上注释，用在属性上。
• @ApiOperation("hello的控制类")：给controller中的接口加上注释，只能放在方法上。
• @ApiParam("用户名")：public String hello(@ApiParam("用户名")String username){}