SpringBoot：快速入门 swagger2.x （含swagger注解说明、springboot多环境、dockerfile、nginx）

前言：
首先看一下要实现的效果：
swagger 实现效果 地址：http://swagger.stonestill.cn/swagger-ui.html
使用 java 的 通过 swagger 发布jar包
使用 dockerfile 在服务器执行镜像文件
使用 nginx 正向代理 进行DNS解析
github 地址： https://github.com/Holyson/java-swagger

swagger 实现效果地址：http://swagger.stonestill.cn/swagger-ui.html

github 地址： https://github.com/Holyson/java-swagger

---

1 、 swagger

1.1 安装 swagger

以下所有内容均为 Swagger2.x 版本为前提的教程

可以在maven仓库 获取到 swagger 坐标
在 maven仓库中搜索：io.springfox

将前2个的坐标 copy 的自己的maven工程中（增加 pom.xml 配置如下：）

swagger 核心文件

<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger2artifactId>
    <version>2.9.2version>
dependency>

swagger -ui

<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger-uiartifactId>
    <version>2.9.2version>
dependency>

1.2 SwaggerConfig

一句注解，就可以开启我们的 swagger

@EnableSwagger2 //开启 swagger

1.2.1 配置 swagger 的 docket 实例

如下代码，实现上面这个效果

package com.ctra.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 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 //开启 swagger
public class SwaggerConfig {
    @Bean
    public Docket docket1(Environment environment){
        return new Docket(DocumentationType.SWAGGER_2).groupName("docket1");
    }
    // 配置了 swagger 的 docket 实例
    @Bean
    public Docket docket(Environment environment){
        // 设置需要登录的 swagger 环境
        Profiles profiles = Profiles.of("pro","dev");
        System.out.println(environment);
        // 获取当前设置的环境
        boolean flag = environment.acceptsProfiles(profiles);
        System.out.println(flag);

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("wanglei")
                .apiInfo(apiInfo())
                // enable 是否启动 swagger，如果为false，则 swagger不能再浏览器中访问
                .enable(flag)
                .select()
                // RequestHandlerSelectors：配置要扫描接口的方式
                //  -basePackage：指定要扫描的包 ☆
                //  -any()：扫描全部
                //  -none()：不扫描
                //  -withClassAnnotation：扫描类上的注解，参数是一个注解的反射对象
                //  -withMethodAnnotation：扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.ctra.controller"))
                // 过滤条件
                // .paths(PathSelectors.none())
                .build();
    }

    private ApiInfo apiInfo(){
        // 作者信息
        Contact contact = new Contact("wanglei", "www.baidu.com", "[email protected]");
        return  new ApiInfo(
                "王磊的API",
                "CTRA",
                "1.0",
                "urn:tos",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

关于头部的这里配置，就不做多余的介绍了，大家根据API配置即可

1.3 swagger 的 annotation

关于 swagger 的注解为UI下半部分显示

swagger 2.x 的包下所有的注解

这里只介绍最基础的用法，作为抛砖引玉，读者们可以根据实际需求使用

作用范围	API	使用位置
协议集描述	@Api	用于controller类上
协议描述	@ApiOperation	用在controller的方法上
非对象参数集	@ApiImplicitParams	用在controller的方法上
非对象参数描述	@ApiImplicitParam	用在@ApiImplicitParams的方法里边
对象参数描述	@ApiParam	用在@ApiImplicitParams的方法里边，定义接收的参数形式
描述返回对象的意义	@ApiModel	用在返回对象类上
对象属性	@ApiModelProperty	用在参数对象的字段上
Response集	@ApiResponses	用在controller的方法上
Response	@ApiResponse	用在 @ApiResponses里边

1.3.1 @Api

@Api(tags = "hello接口")
@RestController
public class HelloController {
}

效果如下：

1.3.2 @ApiOperation

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

效果如下：

1.3.3 @ApiParam

@ApiOperation("hello2控制类")
@PostMapping(value = "/hello2")

public String hello2(@ApiParam("用户名") String name) {
   return "hello" + name;
}

效果如下：

1.3.4 @ApiModel

@ApiModel("user实体类")
public class User {
}

效果如下：

1.3.5 @ApiModelProperty

public class User {
    @ApiModelProperty("主键ID")
    private int id;
    @ApiModelProperty("账号")
    private  String name;
    @ApiModelProperty("密码")
    private  String pwd;
}

效果如下：

1.4 swagger 的 版本（dev、prod）切换 ☆☆☆

由于在生产环境下暴露 swagger 接口是不安全的
这里是一个方法，当然可以采用其他方式满足生产环境下屏蔽 swagger
可以在开发阶段设置 swagger的端口切换

1.4.1 配置多环境

在resources 包中创建 多个 properties 如下图所示：

// application.properties
spring.profiles.active=dev
======================================
// application-dev.properties
server.port=8082
======================================
// application-pro.properties
server.port=8081

1.4.2 获取当前环境

在 swagger 的 docket 实例 中 去获取当前环境环境

    // 配置了 swagger 的 docket 实例
    @Bean
    public Docket docket(Environment environment){

        // 设置需要登录的 swagger 环境
        Profiles profiles = Profiles.of("pro","dev");
        System.out.println(environment);
        // 获取当前设置的环境
        boolean flag = environment.acceptsProfiles(profiles);
        System.out.println(flag);
   }

1.4.3 jar包

在生成的 jar 包会根据当前激活的环境
在发布时要注意这点

2. 使用 dockerfile 构建 springboot 项目

后面会更新为 docker composer 服务编排来重新发布此 swagger 的 springboot项目

新建一个脚本文件并且编辑

vim springboot_docker

在vim模式下输入如下

FROM java:8
MAINTAINER wanglei <[email protected]>
ADD swaggerdmeo-2.2.0.RELEASE.jar app.jar
CMD java -jar app.jar

• FROM 基于 java:8 镜像 （如果没有会自动下载 对应的 image）
• MAINTAINER 指令设置生成镜像的 Author 信息
• ADD 复制该文件（这里是 .jar）至镜像中，起别名
• CMD 当启动容器时执行的脚本文件

创建 dockerfile 生成 image 名称为 app

 docker build -f springboot_docker -t app .

查看镜像

docker image

启动镜像 并接口映射

docker run -id -p 8082:8082 app

3. nginx 域名解析

修改nginx配置文件
首先要确认服务器8082的端口是否开放

server {
        listen       80;   
        server_name  swagger.stonestill.cn;
        location / {
            proxy_pass http://127.0.0.1:8082;
        }
}

文中如有任何错误以及问题，欢迎指正，我会及时修正
希望这篇文章对您有一定的帮助
谢谢