SpringBoot學習之swagger2的集成和使用

Swagger是一個流行的API開發框架，用於生成、描述、調用和可視化REST風格的Web服務，這個框架以「開放API聲明」爲基礎，對整個API的開發週期都提供了相應的解決方案，（包括設計、編碼和測試，幾乎支持全部語言。因爲Spring的流行，出現了一個基於Spring的組件swagger-SpringMVC，用於將swagger集成到SpringMVC中來。

Swagger2介紹

  Swagger2是一個能夠構建和調試RESTful接口文檔的組件，利用Swagger2的註解能夠快速的在項目中構建Api文檔，而且提供了測試API的功能，Swagger讓部署管理和使用功能強大的API從未如此簡單。

SpringBoot集成

添加Swagger2依賴

<!-- 引入 Swagger2依賴 -->
<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>

建立Swagger2配置文件

主要是添加註解 @EnableSwagger2和定義Docket的bean類

@Configuration
@EnableSwagger2 // 開啓 swagger2 功能
public class SwaggerConfig {

	private final String	name	= "獨淚了無痕";
	private final String	url		= "https://github.com/dllwh/";
	private final String	email	= "duleilewuhen@sina.com";
	// 是否開啓swagger，正式環境通常是須要關閉的，可根據springboot的多環境配置進行設置
	@Value(value = "${swagger.enabled}")
	private Boolean			swaggerEnabled;

	@Bean
	public Docket restApiDocket() {
		return new Docket(DocumentationType.SWAGGER_2) //
				.apiInfo(apiInfo()) // 用來建立該Api的基本信息（這些基本信息會展示在文檔頁面中）
				.enable(swaggerEnabled) // 是否開啓
				.genericModelSubstitutes(DeferredResult.class) //
				.useDefaultResponseMessages(false) //
				.forCodeGeneration(false) //
				.pathMapping("/").select() // 選擇那些路徑和api會生成document
				.apis(RequestHandlerSelectors.basePackage("org.dllwh")) // 指定掃描的包路徑
				.paths(PathSelectors.any())// 指定路徑處理PathSelectors.any()表明全部的路徑
				.build().pathMapping("/");// 建立
	}

	/**
	 * @方法描述:構建 api文檔的詳細信息函數
	 * @return
	 */
	private ApiInfo apiInfo() {
		// 聯繫人信息：聯繫人名字、聯繫人URL、聯繫人email
		Contact contact = new Contact(name, url, email);
		return new ApiInfoBuilder().title("SpringBoot-Swagger2集成和使用-demo示例") // 標題
				.description("Spring Boot 學習") // 描述
				.contact(contact)// 做者信息
				.version("0.0.1")// 版本
				// .extensions(null) //在basePath 基礎上須要排除的url規則
				// .termsOfServiceUrl("") // 服務條款url
				// .license("") //許可證
				// .licenseUrl("") //許可證url
				.build();
	}
}

添加文檔內容

修改Controller，添加API註解

@RestController
@Api(tags = "博客API")
public class SwaggerController {
	@Autowired
	private BlogService blogService;

	@GetMapping("getBlogById/{id}")
	@ApiOperation(value = "經過ID獲取博客信息")
	@ApiImplicitParam(name = "id", value = "查詢ID", required = true)
	public Map<String, Object> getBlogById(@PathVariable Integer id) {
		Blog blogById = blogService.getBlogById(id);
		if (blogById == null) {
			return Json.fail();
		} else {
			return Json.success(blogById);
		}
	}

	@DeleteMapping("deleteBlogById/{id}")
	@ApiOperation(value = "經過ID刪除博客信息")
	public Map<String, Object> deleteBlogById(@PathVariable Integer id) {
		Blog blogById = blogService.getBlogById(id);
		if (blogById == null) {
			return Json.fail();
		} else {
			blogService.deleteBlogById(id);
			return Json.success(blogById);
		}
	}

	@GetMapping("getAllBlogs")
	@ApiOperation(value = "獲取所有博客信息")
	public Map<String, Object> getAllBlogs() {
		List<Blog> allBlogs = blogService.getAllBlogs();
		if (allBlogs.size() == 0) {
			return Json.fail();
		} else {
			return Json.success(allBlogs);
		}
	}

	@PutMapping("insertBlog")
	@ApiOperation(value = "建立博客信息")
	public Map<String, Object> insertBlog(Blog blog) {
		blogService.insertBlog(blog);
		return Json.success(blog);
	}

	@PutMapping("updateBlog")
	@ApiOperation(value = "博客信息修改")
	public Map<String, Object> updateBlog(Blog blog) {
		blogService.updateBlog(blog);
		return Json.success(blog);
	}
}

屬性配置

Swagger訪問與使用

api首頁路徑

http://127.0.0.1:8219/swagger-ui.html

調試：點擊須要訪問的api列表，點擊try it out!按鈕，便可彈出一下頁面：

執行：

結果：

Swagger經常使用屬性說明

API	說明
Api	用於controller類上，描述Controller的做用，表示標識這個類是swagger的資源
ApiOperation	用在controller的方法上，說明方法的做用
ApiImplicitParams	用在controller的方法上，包含一組參數說明
ApiImplicitParam	用在@ApiImplicitParams的方法裏邊，指定一個請求參數的各個方面
ApiResponses	用在controller的方法上，用於表示一組響應
ApiRespons	用在 @ApiResponses裏邊，通常用於表達一個錯誤的響應信息
ApiModel	用在返回對象類上
ApiModelProperty	用在出入參數對象的字段上，描述對象的一個字段

注意事項

繼承WebMvcConfigurationSupport以後，靜態文件映射會出現問題，須要從新指定靜態資源，在WebConfigurer中添加以下代碼：

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("swagger-ui.html")
            .addResourceLocations("classpath:/META-INF/resources/");
    registry.addResourceHandler("/webjars/**")
            .addResourceLocations("classpath:/META-INF/resources/webjars/");
    registry.addResourceHandler("/favicon.ico")
            .addResourceLocations("classpath:/META-INF/resources/favicon.ico");
}

圖形界面化

swagger-bootstrap-ui

swagger-bootstrap-ui是springfox-swagger的加強UI實現，爲Java開發者在使用Swagger的時候，能擁有一份簡潔、強大的接口文檔體驗。

<!-- Swagger-Bootstrap-UI -->
<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>swagger-bootstrap-ui</artifactId>
	<version>${last-version}</version>
</dependency>

swagger-bootstrap-ui 的默認訪問地址是http://${host}:${port}/doc.html

相關使用方法，請查看Swagger-Bootstrap-UI用戶指南

swagger-ui-layer

<dependency>
  <groupId>com.github.caspar-chen</groupId>
  <artifactId>swagger-ui-layer</artifactId>
  <version>${last-version}</version>
</dependency>

• swagger-ui-layer 最新版jar包地址：https://search.maven.org/search?q=g:com.github.caspar-chen%20AND%20a:swagger-ui-layer
• swagger-ui-layer 的默認訪問地址是http://${host}:${port}/docs.html

總結

  本章節主要是對Swagger的集成和簡單使用進行了說明，詳細的用法，可自行搜索相關資料下，這裏就不闡述了。