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..@Beanpublic 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 配置掃描接口

@Beanpublic 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

@Beanpublic Docket docket(Environment environment) {// 獲取當前環境 是生產環境 啟動swaggerboolean 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，則不能在瀏覽器中使用swaggerselect().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！！！處于安全考慮。而且節省運行的內存。

總結

以上是生活随笔為你收集整理的swagger接口文档使用的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。