Swagger的使用(整合SpringBoot)

Swagger的使用(SpringBoot)

簡介

前後端分離

純後端時代:前端只用管理靜態頁面

前後端分離時代:

  • 後端:後端控制層、服務層、數據庫訪問層

  • 前端:前端控制層、視圖層

    • 僞後端數據,json。(不需要後端,前端也可以跑起來)
  • 前後端交互:通過api

  • 前後端相互獨立,鬆耦合

  • 前後端可以部署在不同的服務器

  • 問題:

    • 前後端集成聯調,前端人員和後端人員無法做到“及時協商,儘早解決”,最終導致問題集中爆發
  • 解決方法:

    • 首先制定計劃,實時更新最新api,降低集成風險
    • 早些年使用word計劃文檔
    • 前後端分離時代可以使用:前端測試後端接口:postman

swagger

  • 號稱世界上最流行的API框架
  • RestFul Api文檔在線自動生成工具–>api文檔和api定義同步更新
  • 直接運行,可以在線測試Api接口
  • 支持多種語言:java、php等等

官網:https://swagger.io/

在項目中使用

引入依賴

新建SpringBoot項目,引入Swagger相關依賴:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.qianyu</groupId>
    <artifactId>demo</artifactId>
    <version>1.0-SNAPSHOT</version>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.1.6.RELEASE</version>
        <relativePath/>
    </parent>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
    </dependencies>
</project>

新建HelloWorld

  • controller
@RestController
public class HelloController {
    @GetMapping("/hello")
    public String hello() {
        return "Hello World";
    }
}
  • 主類
@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}
  • application.yml
server:
  port: 9000
  • Swagger配置類
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket getDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    // 配置Swagger的ApiInfo
    private ApiInfo apiInfo() {
        // 作者信息
        Contact contact = new Contact("芊雨", "http://www.qianyucc.xyz/", "[email protected]");
        return new ApiInfo(
                "芊雨的博客API文檔",
                "博客後端所有的api接口",
                "v1.0.0",
                "http://localhost:8886/",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

運行項目,在瀏覽器訪問http://localhost:9000/swagger-ui.html,即可看到api文檔:
Swagger文檔

配置包掃描和只在開發環境生效

  • 新建application-dev.ymlapplication-pro.yml分別表示開發環境和生產環境
  • application.yml中啓用開發環境
server:
  port: 9000
spring:
  profiles:
    active: dev
  • 修改配置類
@Bean
public Docket getDocket(Environment environment) {
    // 如果在dev環境(開發環境)就開啓Swagger
    boolean isDev = environment.acceptsProfiles(Profiles.of("dev"));
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .enable(isDev)
            .select()
            // 配置需要掃描的包
            .apis(RequestHandlerSelectors.basePackage("com.qianyu.demo.controller"))
            // 配置需要匹配的路徑
            //.paths(PathSelectors.ant("/api/**"))
            .build();
}

這時候只有在開發環境中訪問http://localhost:9000/swagger-ui.html才能看到文檔內容

分組功能的實現

在Swagger配置類中,我們可以只用多個Docket對象來完成分組,因爲在開發過程中每個人可能負責一個模塊,所以每個人都可以配置一個屬於自己的Docket,並且在裏面實現個性化配置

@Bean
public Docket docket1() {
    return new Docket(DocumentationType.SWAGGER_2).groupName("張三");
}

@Bean
public Docket docke2() {
    return new Docket(DocumentationType.SWAGGER_2).groupName("李四");
}

@Bean
public Docket docket3() {
    return new Docket(DocumentationType.SWAGGER_2).groupName("王五");
}

文檔註釋

默認情況下,只要接口的返回值中存在實體類,就會被掃描到Swagger中

@PostMapping("/user")
public User user() {
    return new User();
}

如圖所示:
SwaggerModel

我們也可以使用註解來書寫註釋

@ApiModel("用戶實體類")
public class User {
    @ApiModelProperty("用戶名")
    private String username;
    @ApiModelProperty("用戶id")
    private Integer id;
    @ApiModelProperty("用戶密碼")
    private String password;
}
@ApiOperation("查詢用戶名是否存在")
@GetMapping("/demo")
public String demo(@ApiParam("用戶名") String username) {
    return "res:" + username;
}

此時,在文檔上就會出現我們自定義的註釋:

中文註釋

發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章