架構實戰篇（二）：Spring Boot 整合Swagger2

weixin_34037977發表於2018-02-01
架構Spring BootSwagger

你還在跟前端對接上花費很多的時間而沒有效果嗎？
你還在為寫介面文件而煩惱嗎？

今天就教大家一個介面對接神器 Swagger
Swagger 可以幫我們快速的展示介面的定義以及快速介面的呼叫測試

先讓我們看下這個神器的真面目吧

9260441-e03fd1c3a76e8613.png

是不是發現都有哪些介面一目瞭然？

下面就讓我們的專案整合上Swagger2吧

預設我們這些東西都是需要有的： Jdk1.6+，Maven

完整的目錄結構如下圖

9260441-6ad5aaf00744df44.png
目錄結構

增加Maven 依賴

<?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.example</groupId>
    <artifactId>spring-boot-swagger</artifactId>
    <version>1.0-SNAPSHOT</version>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>1.5.1.RELEASE</version>
    </parent>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency>
            <groupId>org.apache.tomcat.embed</groupId>
            <artifactId>tomcat-embed-jasper</artifactId>
        </dependency>
        <!-- 打war包用 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-tomcat</artifactId>
            <scope>provided</scope>
        </dependency>
    </dependencies>
    <packaging>war</packaging>
    <!-- -->
    <properties>
        <java.version>1.8</java.version>
    </properties>
    <build>
        <!-- 打war包用 -->
        <finalName>swagger</finalName>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
            <!-- 打war包用,maven打包的時候告訴maven不需要web.xml,否剛會報找不到web.xml錯誤 -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-war-plugin</artifactId>
                <version>2.1.1</version>
                <configuration>
                    <failOnMissingWebXml>false</failOnMissingWebXml>
                </configuration>
            </plugin>
            <!-- -->
        </plugins>
    </build>
</project>

springfox-swagger2 是主要核心， springfox-swagger-ui 是官網提供的免費UI介面

增加Spring boot 入口

package com.example;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

```properties
server.port=8081
server.context-path=/swagger
swagger.enable=true

使用註解配置Swagger

package com.example.configuration;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
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.sql.Timestamp;
import java.util.Date;

@Configuration
@EnableSwagger2
public class Swagger2Config {

    public static final String BASE_PACKAGE = "com.example";

    @Value("${swagger.enable}")
    private boolean enableSwagger;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 生產環境的時候關閉 swagger 比較安全
                .enable(enableSwagger)
                //將Timestamp型別全部轉為Long型別
                .directModelSubstitute(Timestamp.class, Long.class)
                //將Date型別全部轉為Long型別
                .directModelSubstitute(Date.class, Long.class)
                .select()
                // 掃描介面的包路徑，不要忘記改成自己的
                .apis(RequestHandlerSelectors.basePackage(BASE_PACKAGE))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger RESTful APIs")
                .description("Swagger API 服務")
                .termsOfServiceUrl("http://swagger.io/")
                .contact(new Contact("Swagger", "127.0.0.1", "qiaohhgz@163.com"))
                .version("1.0")
                .build();
    }
}
  • 正常專案上線後應該是關閉掉 swagger 的，所以這邊增加了一個配置 enableSwagger
  • 可以使用 directModelSubstitute 做一些期望的型別轉換

增加兩個Java 傳輸物件

package com.example.model;

import com.fasterxml.jackson.annotation.JsonIgnore;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("使用者")
public class User {
    @ApiModelProperty("編號")
    private Long id;

    @ApiModelProperty("使用者名稱")
    private String username;

    @ApiModelProperty("姓")
    private String firstName;

    @ApiModelProperty("名")
    private String lastName;

    @ApiModelProperty("郵箱")
    private String email;

    @ApiModelProperty(hidden = true)// 密碼不傳輸
    @JsonIgnore
    private String password;

    @ApiModelProperty("狀態")
    private Integer userStatus;

    // 省略了get set
}
  • ApiModelProperty 只設定value 值的時候可以不寫 value = ""
  • password 我們用了 JsonIgnore 和 hidden = true 設定，不希望密碼傳輸到前端去
package com.example.model;

import io.swagger.annotations.ApiModelProperty;

public class UserForm {
    @ApiModelProperty(value = "使用者名稱", required = true, example = "admin")
    private String username;
    @ApiModelProperty(value = "密碼", required = true, example = "000000")
    private String password;

    // 省略了get set
}
  • 使用 example 可以提供一些測試內容，方便測試

編寫一個首頁的Controller

package com.example.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;

@Api(value = "首頁", description = "首頁")
@RequestMapping("/")
@RestController
public class IndexController {
    @ApiOperation(value = "Hello Spring Boot", notes = "Hello Spring Boot")
    @RequestMapping(value = "/", method = RequestMethod.GET)
    public String index() {
        return "Hello Spring Boot";
    }

    @ApiOperation(value = "API 頁面", notes = "介面列表")
    @RequestMapping(value = "/api", method = RequestMethod.GET)
    public void api(HttpServletResponse response) throws IOException {
        response.sendRedirect("swagger-ui.html");
    }
}
  • 為了方便訪問swagger ui 頁面，我們做了一個重定向 api 更方便些

再來一個常用的簡單登入Controller

package com.example.controller;
import com.example.model.User;
import com.example.model.UserForm;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

@Api(value = "使用者", description = "使用者")
@RequestMapping("/user")
@RestController
public class UserController {

    @ApiOperation(value = "登入", notes = "輸入使用者名稱和密碼登入")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "OK", response = User.class, responseContainer = "user"),
            @ApiResponse(code = 405, message = "賬號名或密碼錯誤")
    })
    @RequestMapping(value = "/login", produces = {"application/json"}, method = RequestMethod.POST)
    ResponseEntity<User> login(@RequestBody UserForm form) {
        if (!form.getPassword().equalsIgnoreCase("000000")) {
            return ResponseEntity.status(HttpStatus.METHOD_NOT_ALLOWED).build();
        }
        User user = new User();
        user.setId(1L);
        user.setUsername(form.getUsername());
        user.setFirstName("小");
        user.setLastName("明");
        user.setEmail("xiaoming@mail.com");
        user.setUserStatus(1);
        return ResponseEntity.ok(user);
    }
}
  • 建議使用Spring的 ResponseEntity 類做統一的返回結果
  • swagger 對 response code 的支援還算好，我們可以把可能出現的異常程式碼都一一羅列出來，方便對接的時候對異常的處理

啟動伺服器，開啟瀏覽器訪問下吧

http://localhost:8081/swagger/api

使用說明

9260441-5a48d9300c7a42c9.png
點選並檢視介面
9260441-48e6538bb03fda3a.png
點選Model 檢視返回內容的資料結構
9260441-91a854b3dba9d668.png
點選Example 檢視案例資料
9260441-642cbd9cb90bb8bc.png
點選Model 檢視請求資料結構
9260441-8c9b57b616362448.png
點選案例可以快速設定請求內容
9260441-490838bf8b516ae0.png
檢視並處理異常code的描述
9260441-a36f4110930ad98a.png
點選Try it out! 執行並檢視結果

就這麼簡單！你學會了嗎？

更多精彩內容

架構實戰篇（一）：Spring Boot 整合MyBatis
架構實戰篇（二）：Spring Boot 整合Swagger2
架構實戰篇（三）：Spring Boot 整合MyBatis(二)
架構實戰篇（四）：Spring Boot 整合 Thymeleaf
架構實戰篇（五）：Spring Boot 表單驗證和異常處理
架構實戰篇（六）：Spring Boot RestTemplate的使用

關注我們

如果需要原始碼可以關注“IT實戰聯盟”公眾號並留言（原始碼名稱+郵箱），小萌看到後會聯絡作者傳送到郵箱，也可以加入交流群和作者互撩哦~~~！

9260441-fbb877c1ace32df7.jpg

IT實戰聯盟是集產品、UI設計、前後端、架構、大資料和AI人工智慧等為一體的實戰交流服務平臺！聯盟嘉賓都為各網際網路公司專案的核心成員，聯盟主旨是“讓實戰更簡單”，歡迎來撩~~~

相關文章