前言：
首先看一下要實現的效果：
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 核心文件
<!-- 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>
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;
}
}
文中如有任何錯誤以及問題，歡迎指正，我會及時修正
希望這篇文章對您有一定的幫助
謝謝