swagger介面檔案
- 一，swagger簡介
- 前后端分離
- swagger 誕生
- 二，springboot集成swagger
- 依賴
- 撰寫helloworld介面
- 配置swagger ==> config 配置類
- 測驗運行
- 三，配置swagger
- swagger 配置掃描介面
- 如何做到只在生產環境中啟動swagger？
- 配置api檔案的分組
- 四，swagger注解用于對物體類，介面的描述
- pojo
- controller
- 五，你以為的是swagger只能提供介面描述資訊？呵~
- swagger能測驗呀
- 六，最后
一，swagger簡介
前后端分離
vue + springboot 一套解決方案
后端時代：前端只用管理靜態頁面；html===>后端，模板引擎 jsp ejb 后端是主力
前后端分離時代：
- 后端：后端控制層，服務層，資料訪問層 【后端團隊】
- 前端：前端控制層（雙向系結），視圖層【前端團隊】
- 偽造后端資料，json，已經存在，無需后端，全段工程依舊能夠跑起來，
- 前后端如何互動？===> API json
- 前后端相對獨立，松耦合
- 前后端可用部署在不同的服務器上
前后端分離產生，一個問題
- 前后端集成聯調，前端和后端人員無法做到，”即時協商，盡早解決“，最終導致問題集中爆發
解決方法：
-
指定schema 【計劃的提綱】，實時更新最新api，降低集成的風險；
-
早些年：制定word計劃檔案；
-
前后端分離：
- 前端測驗后端介面：postman
- 后端提供介面，需要實時更新最新的訊息及改動！
swagger 誕生
- 號稱世界上最流行的api框架
- restful api檔案在線自動生成工具=> api 檔案與api定義同步更更新
- 直接運行，在線測驗api介面
- 支持多種語言 java,php,py…
官網：https://swagger.io
在專案中使用swagger springbox
- swagger2
- ui
二，springboot集成swagger
依賴
-
匯入相關依賴
- springfox-swagger2
- springfox-swagger-ui
-
pom
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <!-- 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>
撰寫helloworld介面
package cn.bitqian.swagger.controller;
import org.springframework.web.bind.annotation.*;
/**
* hello world
* @author echo lovely
* @date 2020/10/28 19:23
*/
@RestController
public class HelloController {
@RequestMapping(value = "/hello")
public String hello() {
return "hello";
}
}
配置swagger ==> config 配置類
開啟swagger，Enablexxx
@Configuration
@EnableSwagger2 // 開啟swagger2
public class SwaggerConfig {
}
測驗運行
http://localhost:8080/swagger-ui.html
三，配置swagger
來告訴交接人員，介面是干嘛的，對controller的介面進行描述，也可以設定介面訪問權限，
package cn.bitqian.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;
/**
* swagger配置類
* @author echo lovely
* @date 2020/10/28 19:35
*/
@Configuration
@EnableSwagger2 // 開啟swagger2
public class SwaggerConfig {
// 檔案的標題，和描述！作者的資訊deng..
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(appInfo());
}
// api 資訊 介面檔案的頭部資訊描述
public ApiInfo appInfo() {
Contact contact = new Contact("bitqian", "http://example.com", "admin-@www.example.cn");
return new ApiInfo("bitqian的swagger檔案",
"用來描述此介面的功能，內容，",
"v1.0",
"http://example.cn", contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
swagger 配置掃描介面
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(appInfo()).
select().
// RequestHandlerSelectors 配置要掃描的介面的方式
// basePackage 指定要掃描的包
// any() 掃描全部
// none() 不掃描
// withClassAnnotation(Controller.class) 掃描類上的注解, 生效
// withMethodAnnotation(RequestMapping.class) 掃描方法上的注解, 生效
apis(RequestHandlerSelectors.basePackage("cn.bitqian.swagger.controller")).
// paths(PathSelectors.ant("/bitqian/**")) 掃描指定的介面
// PathSelectors.regex("")
paths(PathSelectors.ant("/hello/**"))
.build();
}
如何做到只在生產環境中啟動swagger？
- 判斷是否是生產環境
- 注入enable
@Bean
public Docket docket(Environment environment) {
// 獲取當前環境 是生產環境 啟動swagger
boolean isProFlag = environment.acceptsProfiles(Profiles.of("pro"));
System.out.println("is dev environment....===========>" + isProFlag);
return new Docket(DocumentationType.SWAGGER_2).apiInfo(appInfo()).groupName("bitqian").
enable(isProFlag). // 是否啟動swagger 如果為false，則不能在瀏覽器中使用swagger
select().
apis(RequestHandlerSelectors.basePackage("cn.bitqian.swagger.controller")).
// paths(PathSelectors.ant("/hello/**")).
build();
}
配置api檔案的分組
- 整出多個docket，多個人寫不同的介面
@Bean
public Docket docket1() {
return new Docket(DocumentationType.SWAGGER_2).groupName("bitqian666 group1");
}
@Bean
public Docket docket12() {
return new Docket(DocumentationType.SWAGGER_2).groupName("bitqian666 group2");
}
四，swagger注解用于對物體類，介面的描述
pojo
package cn.bitqian.swagger.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
/**
* 給物體類生成檔案
* @author echo lovely
* @date 2020/10/29 21:09
*/
@ApiModel("user物體類")
public class User {
@ApiModelProperty("用戶名")
public String username;
@ApiModelProperty("密碼")
public String password;
public User() {}
public User(String username, String password) {
this.username = username;
this.password = password;
}
}
controller
package cn.bitqian.swagger.controller;
import cn.bitqian.swagger.entity.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;
/**
* hello world
* @author echo lovely
* @date 2020/10/28 19:23
*/
@RestController
public class HelloController {
@ApiOperation("get/post都可的hello介面")
@RequestMapping(value = "/hello")
public String hello() {
return "hello";
}
@ApiOperation("get的hello介面, 回傳一個空 user")
@GetMapping(value = "/hello1")
public User hello1() {
return new User();
}
@ApiOperation("hello1 介面post way~")
@PostMapping(value = "/hello1")
public User hello1(@ApiParam("傳遞用戶") User user) {
return user;
}
@ApiOperation("登錄介面 post way~")
@PostMapping(value = "/login")
public String login(@ApiParam("登錄用戶名") @RequestParam("username") String username,
@ApiParam("登錄密碼") @RequestParam("password") String password) {
return "ok" + "{" + username + ", " + password + "}";
}
}
五，你以為的是swagger只能提供介面描述資訊？呵~
swagger能測驗呀
try it out
六，最后
- 我們可用通過swagger給一些比較難理解的屬性或者介面，增加注釋資訊
- 介面檔案實時更新
- 可以在線測驗
swagger是一個優秀的工具，幾乎所有大公司都有使用它，更符合迭代開發的需求，
【注意點】 在正式發布的時候，關閉swagger！！！處于安全考慮，而且節省運行的記憶體，
轉載請註明出處，本文鏈接：https://www.uj5u.com/qianduan/198604.html
標籤：其他