最全面细致！SpringBoot项目使用Swagger开发文档管理框架

一、依赖引入及配置

1、使用swagger首先在SpringBoot项目的POM.xml下引入依赖，使用版本推荐2.0，可以在Maven官网https://mvnrepository.com/搜索springfox-swagger如下：

①先引入swagger2，自行选择版本，注意与UI版本一致：

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

②再引入swagger UI 版本与上一致：

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

③如果运行报错，说明缺少日志依赖：

        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-simple</artifactId>
            <version>1.7.25</version>
            <scope>compile</scope>
        </dependency>

2、config包下一个配置类SwaggerConfig

package com.meng.swagger.config;


import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.ApiInfoBuilder;
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;

@Configuration
@EnableSwagger2 //开启
public class SwaggerConfiig {

    //swagger的bean实例
    @Bean
    public Docket docket(Environment environment){
        //设置要显示的swagger环境，项目中一般有发布前的开发坏境，发布后生产环境，配置文件aproperties多样
        Profiles profiles = Profiles.of("dev","test");  //获得apropeties文件，参数可以是多个
        //通过environment.acceptsProfiles获取项目环境判断是否处在自己设定的环境当中
        boolean flag = environment.acceptsProfiles(profiles);


        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("meng")  //api分组
                //true表示打开swagger,false表示关闭,不写enable默认true，flag是上面Profiles.of获取项目环境看处于哪个阶段判读是否打开swagger，是dev配置文件则打开
                //多个aproperties文件中如application.properties、application-dev.properties、application-pro.properties
                //当application.properties中spring.profiles.active=dev，则指定激活application-dev.properties，则flag为true，这种好处是在配置文件就可以决定是否打开swagger
                .enable(flag)
                .select()
                //RequestHandlerSelectors.basePackage("com.meng.swagger.controller")配置要扫描的接口的方式，只会扫描该包下的接口,此为常用
                //.any() 表示全部扫描
                //.none()表示都不扫描
                //.withClassAnnotation(RestController.class)表示扫描类上有@RestController注解的类上接口
                //.withMethodAnnotation(GetMappering)扫描GetMappering方法接口
                .apis(RequestHandlerSelectors.basePackage("com.meng.swagger.controller"))
                //过滤,只扫描meng下面的接口
//                .paths(PathSelectors.ant("/meng/**"))
                .build();
    }
    //多人开发会有多个Bean实例,即分组开发接口
    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("张三"); //其余配置同上
    }
    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("李四");
    }



    //接口的提示信息，项目说明等
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("XXX项目接口")//大标题
                .description("有点酷")//详细描述
                .version("2.0")//版本
                .termsOfServiceUrl("https://www.cnblogs.com/Meng2113/")
                .contact(new Contact("meng", "https://www.cnblogs.com/Meng2113/", "764730326@qq.com"))//作者
                .license("The Apache License, Version 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                .build();
    }
}

二、使用swagger的测试

1、在controller包下创建一个HelController进行测试

package com.meng.swagger.controller;

import com.meng.swagger.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.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Api(tags = "控制器")//对控制层进行说明
@RestController
public class HelController {

    @ApiOperation("hello控制类")//此注解给接口进行说明
    @GetMapping("/hello")
    public String hel(){
        return "sdsd";
    }
    //只要接口返回值存在实体类，就会被扫描到swagger的model中，但是属性必须是public才会显示，private则会隐藏
    // 可以在实体类上注解@ApiModel("用户实体类")来说明该类作用
    //也可在实体类的某个属性注解@ApiModelProperty("用户名")表示该字段的作用
    @PostMapping("user")
    public User user(String username){
        return new User();
    }
    @ApiOperation("post测试")
    @PostMapping("post")
    public User postt(@ApiParam("用户") User user){
        return new User();
    }
}

2、如果在swagger使用中更人性化的添加注释及说明，可以在controller层及pojo实体类中使用@Api开头的注解

①在控制类中使用注解说明swagger：

@Api(tags = "控制器")//放在控制类上，对控制层进行说明

@ApiOperation("hello控制类")//放在接口方法上，给接口进行说明

@ApiParam("用户")//放在接口方法的参数中，对参数说明

②在实体类中的注解说明swagger：

@ApiModel("用户实体类")  //放在实体类上，说明该类的作用

@ApiModelProperty("用户名") //放在实体类的字段上，说明该属性的作用

2、具体实体类参看如下：

package com.meng.swagger.pojo;

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

@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    public String name;
    @ApiModelProperty("密码")
    public String password;
}

浏览器访问swagger的URL：http://localhost:8080/swagger-ui.html 访问不了就看看端口号有没有改动

3、prpperties文件的说明

由于SpringBoot有多个配置文件。例如application.properties、application-dev.properties、application-pro.properties

假设

application.properties	自带默认配置文件
application-dev.properties	开发过程中使用的配置文件
application-pro.properties	生产使用的配置文件

在开发中我们希望使用swagger，但是到了部署到生产上，swagger的作用就没有了，此时就没必要开启swagger。

所以为了达到该目的。在SwaggerConfig类中可以看到

//设置要显示的swagger环境，项目中一般有发布前的开发坏境，发布后生产环境，配置文件aproperties多样
 Profiles profiles = Profiles.of("dev","test");  //获得apropeties文件，参数可以是多个

通过profies获取配置文件，如果springboot项目此时激活的配置文件不是dev，则swagger会自行关闭，原因如下：

//通过environment.acceptsProfiles获取项目环境判断是否处在自己设定的环境当中
 boolean flag = environment.acceptsProfiles(profiles);

在经由profies获得环境配置后，我们environment.acceptsProfiles方法判断当前配置文件是否为激活状态并赋值给flag，在返回的Docket中可以发现：

return new Docket(DocumentationType.SWAGGER_2)
　　.enable(flag)

enable决定了swagger的开启和关闭状态，看到这里，就会明白开发和部署后swagger的状态转换了。

具体的简单配置参看如下：

  application.properties

spring.profiles.active=dev //默认配置类激活dev配置文件

  application-dev.properties

server.port=8081 //重新指定端口

  application-pro.properties

server.port=8082

 

ps：大部分的注释在具体类中，可以仔细阅读，或者移步码云直接下载使用：https://gitee.com/meng_jingzeng/swagger-demo