swagger介面檔案使用-有解無憂

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/ruanti/198053.html

標籤：其他

上一篇：Lambda基本使用方法（從代碼理解定義）

下一篇：哈KK成長之路--集合框架