一文搞懂Swagger,讓你明白用了Swagger的好處!!!

前後端分離缺陷

瞭解Swagger之前,需要先知道什麼是前後端分離

現在的時代

SpringBoot + VUE

以前的時代

SSM + JSP模板引擎====>後端程序員

前後端分離時代

通過相關的API接口進行交互

前後端相對獨立,松耦合

前後端可以分別部署在不同的服務器上

僞造後端交互數據,json數據已經存在,不需要後端傳入json數據了,前端工程已經可以運行

後端:後端控制層 + 服務層 + 數據訪問層

前端:前端控制層 + 視圖層

前後端如何交互?

但這樣會產生新問題

前後端集成聯調,前端和後端開發人員無法做到 及時協商,儘早解決問題,就會導致項目延期

解決方案:

前端測試後端:postMan

後端提供接口,需要實時更新最新的消息和改動

首先指定schema[計劃大綱],團隊實時更新最新的API,可以降低集成的風險;

早些年:指定world計劃文檔

前後端分離:

Swagger簡介

Swagger官網

號稱世界上最流行的API框架

RestFul API文檔在線生成工具--->>>==API文檔與API同步更新==

可以直接運行,可以在線測試API接口

支持多種語言:(Java,PHP......)

使用SpringBoot集成Swagger

創建 SpringBoot-Web項目,導入相關依賴

注意事項:

在項目中使用Swagger需要SpringBox

swagger2

swaggerui


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

創建hello程序

擴展,一個hello程序有兩個請求,一個是SpringBoot項目默認的/error

image-20200611133103333

@RestController
public class HelloController {
    /**
     * 測試Controller
     *
     * @return
     */
    @GetMapping("/hello")
    public String hello() {
        return "你好呀!!!Swagger";
    }
}

配置 Swagger,新建 SwaggerConfig

@Configuration // 標識配置類
@EnableSwagger2 // 開啓Swagger
public class SwaggerConfig {
    
}

測試運行

唯一地址:http://localhost:8080/swagger-ui.html

配置Swagger信息

修改 SwaagerConfig

package com.mobai.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;

/**
 * Software：IntelliJ IDEA 2020.1 x64
 * Author: MoBai·傑
 * Date: 2020/6/11 13:33
 * ClassName:SwaggerConfig
 * 類描述：Swagger配置類
 */
@Configuration // 標識配置類
@EnableSwagger2 // 開啓Swagger
public class SwaggerConfig {

    /**
     * 配置了Swagger的Docket的Bean實例
     *
     * @return
     */
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }

    /**
     * 配置Swagger信息
     *
     * @return
     */
    private ApiInfo apiInfo() {
        // 配置作者信息
        Contact contact = new Contact("墨白",
                "https://www.mobaijun.com",
                "[email protected]");
        // 配置API文檔標題
        return new ApiInfo("框架師Api",
                // API文檔描述
                "Api Documentation",
                // API版本號
                "1.0",
                // 配置URL(公司官網/blog地址)
                "https://www.mobaijun.com",
                // 作者信息
                contact,
                // 以下內容默認即可
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

}

Swagger配置掃描接口

Docket.select();

在 SawggerConfig配置類完善配置掃描接口的參數

 /**
  * 配置了Swagger的Docket的Bean實例
  *
  * @return
  */
 @Bean
 public Docket docket() {
     return new Docket(DocumentationType.SWAGGER_2)
             .apiInfo(apiInfo())
             // 配置掃描接口
             .select()
             /*
              *RequestHandlerSelectors,配置要掃描接口的方式
              * 參數說明:
              * basePackage:基於包掃描
              * class:基於類掃描
              * any():掃描全部
              * none():全部都不掃描
              * withMethodAnnotation:通過方法的註解掃描
              * // withMethodAnnotation(GetMapping.class))
              * withClassAnnotation:通過類的註解掃描
              */
             .apis(RequestHandlerSelectors.basePackage("com.mobai.swagger.controller"))
             // .paths()過濾,不掃描哪些接口
             .paths(PathSelectors.any())
             .build();
 }

配置 Swagger啓動

/**
 * 配置了Swagger的Docket的Bean實例
 *
 * @return
 */
@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            // 配置Swagger是否啓動,默認:true
            .enable(false)
            // 配置掃描接口
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.mobai.swagger.controller"))
            .paths(PathSelectors.any())
            .build();
}

小測試:如果有一個需求,需要你判斷在生成環境中使用,在發佈的時候不使用

開發思路

先判斷.enable()是不是等於 false

注入Enable(flag)

實現,添加application-dev.properties生產環境配置和application-pro.properties發佈環境配置
默認application.properties環境配置添加

# 開啓profiles.active監聽,dev測試環境,pro發佈環境
spring.profiles.active=dev

生產環境修改端口號

server.port=8081

發佈環境修改端口號

server.port=8082

SwaggerConfig配置類判斷當前環境

/**
 * 配置了Swagger的Docket的Bean實例
 *
 * @return
 */
@Bean
public Docket docket(Environment environment) {
    // 設置要顯示的Swagger環境
    Profiles profiles = Profiles.of("dev", "test");
    // 通過environment.acceptsProfiles();判斷自己是否在自己設定換的環境當中
    boolean flag = environment.acceptsProfiles(profiles);

    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            // 監聽自己設置的環境
            .enable(flag)
            // 配置掃描接口
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.mobai.swagger.controller"))
            .paths(PathSelectors.any())
            .build();
}

配置API文檔的分組

配置多個組,添加 .groupName()

   /**
     * 配置了Swagger的Docket的Bean實例
     *
     * @return
     */
    @Bean
    public Docket docket(Environment environment) {
        // 設置要顯示的Swagger環境
        Profiles profiles = Profiles.of("dev", "test");
        // 通過environment.acceptsProfiles();判斷自己是否在自己設定換的環境當中
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 配置分組
                .groupName("墨白小組")
                // 監聽自己設置的環境
                .enable(flag)
                // 配置掃描接口
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.mobai.swagger.controller"))
                .paths(PathSelectors.any())
                .build();
}

效果

配置多個組

@Configuration // 標識配置類
@EnableSwagger2 // 開啓Swagger
public class SwaggerConfig {

    /**
     * 添加A組
     * 每個組各司其職
     *
     * @return
     */
    @Bean
    public Docket docket1() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("A");
    }

    /**
     * 添加B組
     *
     * @return
     */
    @Bean
    public Docket docket2() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("B");
    }

    /**
     * 添加C組
     *
     * @return
     */
    @Bean
    public Docket docket3() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("C");
    }

    /**
     * 配置了Swagger的Docket的Bean實例
     *
     * @return
     */
    @Bean
    public Docket docket(Environment environment) {
        // 設置要顯示的Swagger環境
        Profiles profiles = Profiles.of("dev", "test");
        // 通過environment.acceptsProfiles();判斷自己是否在自己設定換的環境當中
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 配置分組
                .groupName("墨白小組")
                // 監聽自己設置的環境
                .enable(flag)
                // 配置掃描接口
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.mobai.swagger.controller"))
                .paths(PathSelectors.any())
                .build();
    }

效果

實體類配置

@ApiModel("用戶實體類") // 添加註釋
public class User {
    // 添加註釋
    @ApiModelProperty("年齡")
    private Integer age;

    @ApiModelProperty("姓名")
    private String name;

    @ApiModelProperty("賬號")
    private String username;

    @ApiModelProperty("密碼")
    private String password;

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

效果

Swagger常用註解

@ApiModel("註釋"):實體類添加註釋
@ApiModelProperty("註釋"):給實體類屬性添加註釋
@ApiOperation("註釋")給接口(Controller)方法添加註釋,放在方法上
@ApiParam("")給方法的參數添加註釋
@Api("")給類添加註釋

controller

package com.mobai.swagger.controller;


import com.mobai.swagger.pojo.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * Software：IntelliJ IDEA 2020.1 x64
 * Author: MoBai·傑
 * Date: 2020/6/11 13:25
 * ClassName:HelloController
 * 類描述： 測試類
 */
@ApiOperation("")
@RestController
public class HelloController {
    /**
     * 測試Controller
     *
     * @return
     */
    @GetMapping("/hello")
    public String hello() {
        return "你好呀!!!Swagger";
    }

    /**
     * 只要我們的接口中,返回值存在實體類,Swagger就會掃描到
     *
     * @return
     */
    @PostMapping("/user")
    public User user() {
        return new User();
    }

    @ApiOperation("Post測試類")
    @PostMapping(value = "/post")
    public User post(@ApiParam("用戶對象") User user) {
        return user;
    }
}

總結

添加 @Configuration註解,標識配置類
添加 @EnableSwagger2註解開啓Swagger
Swagger2
Swagger-ui
創建SpringBoot項目,導入 Swagger依賴
創建 Swagger配置類
配置 Swagger的 Docket的 Bean實例
配置 Swagger信息

我們可以通過Swagger給一些比較難理解的屬性或者接口,增加註釋信息
接口文檔實時更新
可以在線測試
Swagger是一個優秀的工具,幾乎所有的大公司都在用
需要注意:正式發佈的時候,關閉swagger!!!出於安全考慮,而且節省運行內存!

感謝閱讀,如果有幫助到你,請轉發,點擊再看,這是我分享的動力,感謝

本文分享自微信公衆號 - 框架師（mohu121）。
如有侵權，請聯繫 [email protected] 刪除。
本文參與“OSC源創計劃”，歡迎正在閱讀的你也加入，一起分享。

一文搞懂Swagger,讓你明白用了Swagger的好處!!!

前後端分離缺陷

Swagger簡介

使用SpringBoot集成Swagger

配置Swagger信息

Swagger配置掃描接口

配置API文檔的分組

科普熱點快丨三精準計劃導師QQ穩定發佈

企業級低代碼平臺：企業IT部門的得力助手

頭部大模型公司進京趕考，向量數據庫成爲應考神器

阿里雲可觀測 2023 年 5 月產品動態

面向多告警源，如何構建統一告警管理體系？

基於 AIGC，RocketMQ 學習社區探索開源軟件學習新範式

https://yachay.unat.edu.pe/blog/index.php?comment_area=format_blog&comment_component=blog&comment_co

linux以太網驅動總結

【python 圖片搜索】python 快速計算兩個圖片的相似度