SpringBoot入門——使用Swagger構建Restful API文檔

SpringBoot入門——使用Swagger2構建Restful API文檔

本身寫程序測試時寫的，不喜勿噴，可能有錯，歡迎糾正

1、背景

        因爲Spring Boot可以快速開發、便捷部署等特性，相信有很大一部分Spring Boot的用戶會用來構建RESTful API。而咱們構建RESTful API的目的一般都是因爲多終端的緣由，這些終端會共用不少底層業務邏輯，所以咱們會抽象出這樣一層來同時服務於多個移動端或者Web前端。

        這樣一來，咱們的RESTful API就有可能要面對多個開發人員或多個開發團隊：IOS開發、Android開發或是Web開發等。爲了減小與其餘團隊平時開發期間的頻繁溝通成本，傳統作法咱們會建立一份RESTful API文檔來記錄全部接口細節，然而這樣的作法有如下幾個問題：

• 因爲接口衆多，而且細節複雜（須要考慮不一樣的HTTP請求類型、HTTP頭部信息、HTTP請求內容等），高質量地建立這份文檔自己就是件很是吃力的事，下游的抱怨聲不絕於耳。
• 隨着時間推移，不斷修改接口實現的時候都必須同步修改接口文檔，而文檔與代碼又處於兩個不一樣的媒介，除非有嚴格的管理機制，否則很容易致使不一致現象。

        爲了解決上面這樣的問題，本文將介紹RESTful API的重磅好夥伴Swagger2，它能夠輕鬆的整合到Spring Boot中，並與Spring MVC程序配合組織出強大RESTful API文檔。它既能夠減小咱們建立文檔的工做量，同時說明內容又整合入實現代碼中，讓維護文檔和修改代碼整合爲一體，可讓咱們在修改代碼邏輯的同時方便的修改文檔說明。另外Swagger2也提供了強大的頁面測試功能來調試每一個RESTful API。

2、Swagger簡介

        Swagger 是一款RESTFUL接口的文檔在線自動生成+功能測試功能軟件。本文簡單介紹了在項目中集成swagger的方法和一些常見問題。

        Swagger 是一個規範和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。整體目標是使客戶端和文件系統做爲服務器以一樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，容許API來始終保持同步。Swagger 讓部署管理和使用功能強大的API從未如此簡單。

 

3、SpringBoot中應用Swagger2

(1)、新建Maven項目

項目名稱:springboot

(2)、在pom中引入Springboot項目須要的包

新建Maven項目，往其中pom.xml中引入Springboot須要的包

<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.springboot</groupId>
	<artifactId>spring-boot2</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<packaging>jar</packaging>

	<name>springboot</name>
	<url>http://maven.apache.org</url>

	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>1.5.4.RELEASE</version>
	</parent>

	<properties>
		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
		<java.version>1.8</java.version>
	</properties>

	<dependencies>
		<!-- web -->
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>
		<!-- Springboot devtools熱部署 依賴包 -->
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-devtools</artifactId>
			<optional>true</optional>
			<scope>true</scope>
		</dependency>
	</dependencies>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin </artifactId>
				<configuration>
				<!-- 若是沒有該項配置，devtools不會起做用，即應用不會restart -->
					<fork>true</fork>
				</configuration>
			</plugin>
		</plugins>
	</build>

</project>

(3)、在pom中引入Swagger須要的包

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

(4)、建立Swagger2配置類

包名：com.springboot.config

類名：SwaggerConfig

package com.springboot.config;

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
// 啓用swagger
@EnableSwagger2
public class SwaggerConfig {
	  @Bean
	    public Docket createRestApi() {
	        return new Docket(DocumentationType.SWAGGER_2)
	                .apiInfo(this.apiInfo())
                    .groupName("XX組")
	                .useDefaultResponseMessages(false)
	                .enableUrlTemplating(false)
	                .select()
	                .apis(RequestHandlerSelectors.basePackage("com.springboot.controller"))
	                .paths(PathSelectors.any())
	                .build();
	    }

	    private ApiInfo apiInfo() {
	        return new ApiInfoBuilder()
	                .title("Spring Boot Swagger2 By Test")
	                .description("XX項目API")
	                .termsOfServiceUrl("127.0.0.1:8080/test/")
	                .version("0.0.1")
	                .build();
	    }
}

參數說明：

----------------------------------------------------------------------------------

• @Configuration：聲明此類爲配置類,讓Spring加載
• @EnableSwagger2：啓用Swagger2

----------------------------------------------------------------------------------

• apiInfo()：建立該Api的基本信息
• groupName()：設置組名
• useDefaultResponseMessages()：使用默認的響應信息，通常設置false
• enableUrlTemplating(false)：使模板的URL

----------------------------------------------------------------------------------

• apis()：掃描哪些包
• PathSelectors.any()：任何知足條件的路徑

----------------------------------------------------------------------------------

(5)、建立Controller類

包名：com.springboot.controller;

類名：HelloController

package com.springboot.controller;

import static org.springframework.util.MimeTypeUtils.APPLICATION_JSON_VALUE;
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;
import com.springboot.entity.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;

@RestController
@RequestMapping("/test")
@Api(tags="與檢查單有關的接口")
public class HelloController {

	@ApiOperation(value = "得到hello字符串JSON", response = String.class, produces = APPLICATION_JSON_VALUE
			,notes = "根據User對象建立用戶")
	@RequestMapping(value = { "/hello" }, method = RequestMethod.GET)
	public String hello() {
		return "hello";
	}

	@ApiOperation(value = "修改用戶", response = String.class, produces = APPLICATION_JSON_VALUE
			,notes = "根據id修改用戶")
	@ApiImplicitParam(name = "user", value = "用戶詳細實體user", required = true, dataType = "User")
	@RequestMapping(value = { "/modifyUser" }, method = RequestMethod.POST) 
	public User modifyUser(@RequestBody User user) {
		user.setName("張三");
		user.setAge(20);
		return user;
	}

}

參數說明：

----------------------------------------------------------------------------------

• @Api：對Controller項的標題描述信息設置
• @ApiOperation：對接口信息進行描述

1. name：參數名
2. value：參數描述信息
3. required：是否能夠發送請求信息進行測試
4. dataType：數據類型

• @ApiImplicitParam：對接口的方法的參數進行描述

1. value：操做項名字設置
2. response：返回類型設置
3. response：返回數據格式
4. notes：此項的描述信息

----------------------------------------------------------------------------------

3、管理接口的地址

http://localhost:8080/swagger-ui.html