springfox集成openapi實踐

一 。openapi介紹

  OpenAPI的前身是swagger規範。Swagger是一套有助於先後端分離，接口管理和測試工具集
  SwaggerTM是一個用於描述和文檔化RESTful接口的項目。 
Swagger規範定義了一系列的文件，用以描述API。這些文件能夠被Swagger-UI項目用於展現API，也能夠被Swagger-Codegen項目用於生成代碼。一些其餘的工具也能夠利用這些文件，例如測試工具soapui。

規劃文件格式：

格式是遵循JSON格式的。YAML做爲JSON的一個超集，也是被支持的。 
有關於field，有兩種： 
第一種是fixed fields，是說field的名稱是固定的； 
第二種是Patterned fields，field的名字不是固定的，而是使用正則表達式匹配。

filed名稱大小寫敏感

文件結構

Swagger的規範要求將API用一個單一的文件表示。不過，定義能夠拆成多個文件。使用$ref將他們拼合在一塊兒。這符合JSON Schema規範。 
按照慣例，Swagger規範文件命名爲swagger.json。

Swagger文件根元素（具體節點描述參考官網https://swagger.io/docs/specification/basic-structure/）

名稱	類型	描述
swagger	string	必填。值必須爲「2.0」
info	Info對象	必填。提供有關於API的元數據。
host	string	host地址，域名或者是ip。能夠包含端口，但不得包含其餘路徑
basePath	string	必須以」/」開頭，定義基礎路徑。不支持路徑模板
schemes	string數組	定義傳輸協議，必須從如下選擇：http、https、ws、wss。若是不指定schemes，默認的scheme就是訪問Swagger時訪問的協議
consumes	string數組	定義一系列能夠被消費的MIME類型。
produces	string數組	定義一系列能夠被生產的MIME類型。
paths	Paths對象	必填。可得到的paths和操做符。
definitions	Definitions對象	持有經過操做生產和消費的數據類型
parameters	Parameters Definitions對象	持有操做時使用的參數。
responses	Responses Definitions對象	持有操做的結果。
securityDefinitions	Security Definitions對象	安全策略
security	Security Definitions對象數組	總體安全策略
tags	Tag對象數組	標籤
externalDocs	External Documentation對象	添加外部文檔

基於jax-rf的註解規範 參考（https://github.com/swagger-api/swagger-core/wiki/Annotations-2.X）

使用springfox集成swagger 參考（https://github.com/springfox/springfox） 點擊文檔可進入

http://springfox.github.io/springfox/docs/current/

二。 openapi工具集swagger

swagger是圍繞openapi規範構建的一組開源工具，能夠幫助您設計、構建、記錄和使用RESTAPI。 
主要的swagger工具包括：

•     swagger編輯器--基於瀏覽器的編輯器，您能夠在其中編寫openapi規範。
•    swagger UI--將openapi規範呈現爲交互式API文檔（界面展現openapi規範文件 更清晰明瞭）。
•    swagger codegen--從openapi規範生成服務器存根和客戶機庫。

1. 安裝swagger編輯器 

編輯器能夠編輯openapi規範文件 預覽ui效果等 安裝過程參考 （https://swagger.io/docs/swagger-tools/#swagger-editor-documentation-0）

準備服務器 centos7 ip 192.168.58.144

swagger編輯器 須要nodejs環境支持 

yum -y install epel-release.noarch 
yum -y install nodejs npm

安裝swagger編輯器

yum -y install openssl openssl-devel
wget https://github.com/swagger-api/swagger-editor/releases/download/v2.10.4/swagger-editor.zip
unzip swagger-editor.zip
http-server swagger-editor

啓動後使用瀏覽器訪問

http://192.168.58.144:8080/#/

界面出現能夠左側便捷openapi  右側ui方式顯示 菜單項 Generate Server能夠生成不一樣環境下的服務器代碼 也能夠生成調用的客戶端代碼

2 安裝swaggerui

ui是能夠直接經過讀取openapi文檔來直接可視化api 

官網文檔提供的是2.X版本安裝 3.X版本 直接解壓便可用 不過沒找到漢化的方式 這裏就安裝官方文檔安裝2.X吧

文檔地址:https://swagger.io/docs/swagger-tools/
github地址：https://github.com/swagger-api/swagger-ui（這是3.X）
3.X代碼下文檔有提供2.X代碼地址 https://github.com/swagger-api/swagger-ui/tree/2.x
下載zip代碼包

解壓後目錄 swagger-ui-2.x\dist 就是ui的目錄 進入dist目錄 雙擊index.html能夠單擊使用 也能夠服務器部署使用

cd swagger-ui-2.x\dist && http-server -p8888

訪問地址 

http://192.168.58.144:8888/

界面效果爲（默認有個openapi的json 能夠點擊explore預覽ui效果）：、

漢化過程參考官方文檔

打開index.html文件 將js的如下兩行放開 將js替換成 zh-cn.js

<!-- Some basic translations -->
  <script src='lang/translator.js' type='text/javascript'></script>
  <script src='lang/zh-cn.js' type='text/javascript'></script>

漢化後的界面是

三 。springfox集成 swagger

springboot使用springfox集成swagger2（http://springfox.github.io/springfox/docs/current/#springfox-support-for-jsr-303）

添加maven依賴

<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>cn.et</groupId>
	<artifactId>springfox</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.0.0.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.8.0</version>
		</dependency>
		<dependency>
    <groupId>io.springfox.ui</groupId>
    <artifactId>springfox-swagger-ui-rfc6570</artifactId>
    <version>1.0.0</version>
</dependency>
	</dependencies>
</project>

添加main方法測試

package springfox;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;

import io.swagger.annotations.ApiOperation;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger.web.DocExpansion;
import springfox.documentation.swagger.web.ModelRendering;
import springfox.documentation.swagger.web.OperationsSorter;
import springfox.documentation.swagger.web.TagsSorter;
import springfox.documentation.swagger.web.UiConfiguration;
import springfox.documentation.swagger.web.UiConfigurationBuilder;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Controller
@EnableAutoConfiguration
@EnableSwagger2

public class RestController {

	@ApiOperation(value = "helloworld方法",
		      notes = "${RestController.home}") 
	@RequestMapping(value="/",method=RequestMethod.GET)
	@ResponseBody
	String home() {
		return "Hello World!";
	}

	public static void main(String[] args) throws Exception {
		SpringApplication.run(RestController.class, args);
	}

	@Bean
	  public Docket petApi() {
	    return new Docket(DocumentationType.SWAGGER_2)
	        .select()
	          .apis(RequestHandlerSelectors.any())
	          .paths(PathSelectors.any())
	          .build()
	        .pathMapping("/");
	        
	  }
	  @Bean
	  UiConfiguration uiConfig() {
	    return UiConfigurationBuilder.builder()
	        .deepLinking(true)
	        .displayOperationId(false)
	        .defaultModelsExpandDepth(1)
	        .defaultModelExpandDepth(1)
	        .defaultModelRendering(ModelRendering.EXAMPLE)
	        .displayRequestDuration(false)
	        .docExpansion(DocExpansion.NONE)
	        .filter(false)
	        .maxDisplayedTags(null)
	        .operationsSorter(OperationsSorter.ALPHA)
	        .showExtensions(false)
	        .tagsSorter(TagsSorter.ALPHA)
	        .validatorUrl(null)
	        .build();
	  }
}

其餘api註解參考 官網 訪問swagger-ui界面（http://localhost:8080/swagger-ui.html#/rest-controller）