2. 程式人生 > 實用技巧 >介面文件（採用Swagger框架）

介面文件（採用Swagger框架）

阿新 • • 發佈：2020-11-20

傳統的介面文件（版本迭代時，介面文件有可能沒有更新），所以採用swagger框架，可以通過註解的方式來生成文件

開發中，可以將需求文件、資料庫、介面文件等放在test測試目錄resource下，工程打包時，並不會打包test目錄下的檔案

swagger資料夾
controller層上的註解生成文件案例
package cn.kooun.controller;

import java.io.Serializable;

import javax.servlet.http.HttpServletRequest;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import com.alibaba.fastjson.JSON;

import cn.kooun.common.ResponseUtil;
import cn.kooun.common.check.CheckUtil;
import cn.kooun.common.result.ResultInfo;
import cn.kooun.service.base.MsgService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;

/**
 * swagger控制層案例
 */
@RestController
//介面模組描述
@Api(tags = "swagger演示模組")
@RequestMapping("/swaggerDemo")
public class SwaggerDemoContrller {
	
	@Autowired
	private MsgService msgService;
	/**
	 * 表單請求案例
	 * @param userId
	 * @param code
	 * @return
	 */
	//value=介面名稱, notes=介面描述
	@ApiOperation(value = "表單請求案例", notes = "請求使用表單請求")
	@PostMapping("/demoQuery")
	@ApiImplicitParams({
		//paramType=引數請求型別 (query=表單請求,body=json請求)
		//name = 引數名稱
		//value = 引數名稱描述
		@ApiImplicitParam(name="userId",value="使用者id",paramType="query"),
		@ApiImplicitParam(name="code",value="驗證碼",paramType="query")
		})
	@ApiResponses({
		@ApiResponse(code=200,message=ResultInfo.COMMON_JSON),})
	public Object demoQuery(
			HttpServletRequest request,
			@ApiParam()String userId,
			String code) {
		//返回測試資料
		if(CheckUtil.checkDebugRsponse(request)) {
			//從t_debug_response表中獲取json格式資料
			return JSON.parse(msgService.getDebugResponse(1L));
		}
		return ResponseUtil.success();
	}
	
	/**
	 * json請求案例
	 * @param user
	 * @return
	 */
	@ApiOperation(value = "json請求案例", notes = "請求使用json請求")
	@PostMapping("/demoJson")
	@ApiImplicitParams({
		@ApiImplicitParam(name="userId",value="使用者id",required=true,paramType="body"),
		@ApiImplicitParam(name="userName",value="使用者名稱稱",paramType="body")
		})
	@ApiResponses({
		@ApiResponse(code=200,message=ResultInfo.COMMON_JSON),})
	public Object demoJson(HttpServletRequest request, @RequestBody User user) {
		System.out.println(user);
		//返回測試資料
		if(CheckUtil.checkDebugRsponse(request)) {
			return JSON.parse("{\r\n" + 
					"  'result': '業務結果',\r\n" + 
					"  'message': '彈窗訊息',\r\n" + 
					"  'status': '響應狀態',\r\n" + 
					"  'target': '錯誤提示',\r\n" + 
					"  'jump': '跳轉頁面'\r\n" + 
					"}");
		}
		return ResponseUtil.success();
	}
	public static void main(String[] args) {
		System.out.println(JSON.toJSONString(ResponseUtil.error("錯誤原因")));
	}
}



/**
 * model
 * @author chenwei
 * @date 2019年6月25日 下午5:29:54
 */
class User implements Serializable{
	/**
	 * 
	 */
	private static final long serialVersionUID = 306021471164575961L;
	private String userId;
	private String userName;
	public String getUserId() {
		return userId;
	}
	public void setUserId(String userId) {
		this.userId = userId;
	}
	public String getUserName() {
		return userName;
	}
	public void setUserName(String userName) {
		this.userName = userName;
	}
	@Override
	public String toString() {
		return "User [userId=" + userId + ", userName=" + userName + "]";
	}
	
	
}
自定義請求介面引數上的註解生成文件案例
package cn.kooun.pojo.request;

import java.util.Date;

import javax.persistence.Table;

import cn.kooun.pojo.base.Uuid_IDDate;
import io.swagger.annotations.ApiModelProperty;
/**
 * 請求引數封裝案例
 * @author chenwei
 * @date 2019年8月2日 下午3:12:54
 */
public class RequestModel {

	@ApiModelProperty(value="商家Id",name="suserid",required=true)
	private String suserid;
	
	@ApiModelProperty(value="分類Id",name="goodstypeid",required=true)
    private String goodstypeid;
	
	@ApiModelProperty(value="商品名稱",name="suserid",required=true)
    private String goodsname;
	
	@ApiModelProperty(value="商品名稱小寫狀態",hidden=true)
    private String goodsnameIndex;
	
	@ApiModelProperty(value="計算單位",name="unittype",required=true)
    private Integer unittype;
	
	@ApiModelProperty(value="單價",name="unitprice",required=true)
    private String unitprice;
	
	@ApiModelProperty(value="待售數量",name="count",required=true)
    private String count;
	
	@ApiModelProperty(value="是否特色優品 0=否 1=是",name="superiorstatus",required=true)
    private Integer superiorstatus;
	
	@ApiModelProperty(value="特色優品是否錯選 0=否 1=是",name="issuperror",required=true)
    private Integer issuperror;
	
	@ApiModelProperty(value="商品圖片",name="pic")
    private String pic;
	
	@ApiModelProperty(value="商品簡介/促銷廣告",name="introduce")
    private String introduce;
	
	@ApiModelProperty(value="狀態 0=下架 1=上架",name="status",required=true)
    private Integer status;
	
	@ApiModelProperty(value="上架時間",example="2019-06-27 16:56:00",name="upframeTime")
    private Date upframeTime;
	
	@ApiModelProperty(value="下架時間",example="2019-06-27 16:56:00",name="downframeTime")
    private Date downframeTime;


   
    public String getSuserid() {
        return suserid;
    }

    public void setSuserid(String suserid) {
        this.suserid = suserid;
    }

    public String getGoodstypeid() {
        return goodstypeid;
    }

    public void setGoodstypeid(String goodstypeid) {
        this.goodstypeid = goodstypeid;
    }

    public String getGoodsname() {
        return goodsname;
    }

    public void setGoodsname(String goodsname) {
        this.goodsname = goodsname;
    }

    public String getGoodsnameIndex() {
        return goodsnameIndex;
    }

    public void setGoodsnameIndex(String goodsnameIndex) {
        this.goodsnameIndex = goodsnameIndex;
    }

    public Integer getUnittype() {
        return unittype;
    }

    public void setUnittype(Integer unittype) {
        this.unittype = unittype;
    }

    public String getUnitprice() {
        return unitprice;
    }

    public void setUnitprice(String unitprice) {
        this.unitprice = unitprice;
    }

    public String getCount() {
        return count;
    }

    public void setCount(String count) {
        this.count = count;
    }

    public Integer getSuperiorstatus() {
        return superiorstatus;
    }

    public void setSuperiorstatus(Integer superiorstatus) {
        this.superiorstatus = superiorstatus;
    }

    public Integer getIssuperror() {
        return issuperror;
    }

    public void setIssuperror(Integer issuperror) {
        this.issuperror = issuperror;
    }

    public String getPic() {
        return pic;
    }

    public void setPic(String pic) {
        this.pic = pic;
    }

    public String getIntroduce() {
        return introduce;
    }

    public void setIntroduce(String introduce) {
        this.introduce = introduce;
    }

    public Integer getStatus() {
        return status;
    }

    public void setStatus(Integer status) {
        this.status = status;
    }

    public Date getUpframeTime() {
        return upframeTime;
    }

    public void setUpframeTime(Date upframeTime) {
        this.upframeTime = upframeTime;
    }

    public Date getDownframeTime() {
        return downframeTime;
    }

    public void setDownframeTime(Date downframeTime) {
        this.downframeTime = downframeTime;
    }


}
main下配置swagger
package cn.kooun.core.config;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;

import cn.kooun.common.ip.IpUtil;
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;

/**
 * 	swagger配置類
 *
 */
@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class Swagger2Config implements WebMvcConfigurer {

	/**
	 *
	 * 顯示swagger-ui.html文件展示頁，還必須注入swagger資源：
	 * 
	 * @param registry
	 */
	@Override
	public void addResourceHandlers(ResourceHandlerRegistry registry) {
		registry.addResourceHandler("swagger-ui.html")
				.addResourceLocations("classpath:/META-INF/resources/");
		registry.addResourceHandler("doc.html")
				.addResourceLocations("classpath:/META-INF/resources/");
		registry.addResourceHandler("/webjars/**")
				.addResourceLocations("classpath:/META-INF/resources/webjars/");
		
	}

	/**
	 * 載入swagger2
	 * 
	 * @return
	 */
	@Bean
    public Docket buildDocket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //掃描指定的包生成介面文件
                .apis(RequestHandlerSelectors.basePackage("cn.kooun.controller"))
                .paths(PathSelectors.any())
                .build();
    }
	@Value("${server.port}")
	private String serverPort;

	/**
	 * swaggerui頁面資料配置
	 * 文件訪問路徑
	 * http://<ip>:<port>/v2/api-docs
	 * 原版檢視訪問路徑
	 * http://<ip>:<port>/swagger-ui.html
	 * swagger-bootstrap-ui檢視
	 * http://<ip>:<port>/doc.html
	 * @return
	 */
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
				.title("xxx測試服務API")
				.description("空雲資訊科技有限公司@API"
						+ "<p>"
						+ "<font style='color:red'>"
						+ "如果需要獲取業務資料的註釋請在請求頭中新增以下引數"
						+ "debug=1"
						+ "</font>"
						+ "</p>")
				.termsOfServiceUrl("http://"+IpUtil.getLocalIP()+":" + serverPort)
				.version("1.0")
				.build();
		
	}

}
IpUtil類
package cn.kooun.common.ip;

import java.net.InetAddress;
import java.net.NetworkInterface;
import java.util.Enumeration;


/**
 * IP工具類
 */
public class IpUtil {
	

	/**
	 * 此方法描述的是：獲得伺服器的IP地址
	 * 
	 * @author chenwei
	 * @date 2018年4月10日 上午10:50:50
	 * @return
	 */
	public static String getLocalIP() {
		String sIP = "";
		InetAddress ip = null;
		try {
			boolean bFindIP = false;
			Enumeration<NetworkInterface> netInterfaces = NetworkInterface.getNetworkInterfaces();
			while (netInterfaces.hasMoreElements()) {
				if (bFindIP) {
					break;
				}
				NetworkInterface ni = (NetworkInterface) netInterfaces.nextElement();

				Enumeration<InetAddress> ips = ni.getInetAddresses();
				while (ips.hasMoreElements()) {
					ip = (InetAddress) ips.nextElement();
					if (!ip.isLoopbackAddress() && ip.getHostAddress().matches("(\\d{1,3}\\.){3}\\d{1,3}")) {
						bFindIP = true;
						break;
					}
				}
			}
		} catch (Exception e) {
			e.printStackTrace();
		}
		if (null != ip) {
			sIP = ip.getHostAddress();
		}
		return sIP;
	}


}
執行

瀏覽器位址列輸入http://主機ip:埠號/swagger-ui.html

ctrl + h eclipse 的全文搜尋（查bug）

相關推薦

介面文件（採用Swagger框架）

傳統的介面文件（版本迭代時，介面文件有可能沒有更新），所以採用swagger框架，可以通過註解的方式來生成文件

NET Core匯出word文件（表格迴圈插入）

本文以一個簡單的小例子，簡述利用C#語言開發word表格相關的知識，僅供學習分享使用，如有不足之處，還請指正。

Spring Boot從入門到精通（十一）整合Swagger框架，實現自動生成介面文件

Swagger是一個規範和完整的框架，用於生成、描述、呼叫和視覺化 RESTful 風格的 Web 服務。Swagger 是一組開源專案，其中主要要專案如下：

.net core的Swagger介面文件使用教程（一）：Swashbuckle

　　現在的開發大部分都是前後端分離的模式了，後端提供介面，前端呼叫介面。後端提供了介面，需要對介面進行測試，之前都是使用瀏覽器開發者工具，或者寫單元測試，再或者直接使用Postman，但是現在這些都已經out了

.net core的Swagger介面文件使用教程（二）：NSwag

　　上一篇介紹了Swashbuckle ，地址：.net core的Swagger介面文件使用教程（一）：Swashbuckle

介面文件從Swagger升級成knife4j使用教程（springboot）

一、Knife4j是一個為Swagger介面文件賦能的工具 二、引入pom <dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><versio

【開發筆記系列（二）】配置Swagger Api介面文件

首先匯入三個包 Swashbuckle.AspNetCore.Swagger; Swashbuckle.AspNetCore.SwaggerGen; Swashbuckle.AspNetCore.SwaggerUI;

Spring Boot專案開發（五）——整合swagger2自動生成介面文件

一、新增swagger2相關依賴 <!--新增swagger2依賴，自動生成介面文件--> <dependency>

knife4J 配置（生成介面文件）

1、概述 knife4j 是springfox-swagger的增強UI實現，為Java來發者在使用swagger的時候，能擁有一份簡潔、強大的介面文件體驗。

FastAPI 學習之路（二十）介面文件配置相關

　系列文章： 　　FastAPI 學習之路（一）fastapi--高效能web開發框架 　　FastAPI 學習之路（二）

Django（74）drf-spectacular自動生成介面文件

介紹 drf-spectacular是為Django REST Framework生成合理靈活的OpenAPI 3.0模式。它可以自動幫我們提取介面中的資訊，從而形成介面文件，而且內容十分詳細，再也不用為寫介面文件而心煩了

golang gin框架使用swagger生成介面文件

前言 一份清晰明瞭的介面文件能夠極大地提高前後端雙方的溝通效率和開發效率。

C# Swagger-ui 生成介面文件

一、前言 　　相信很多小夥伴對 WebApiTestClient 很熟悉，今天講的是公司目前想更換一個生成介面文件的外掛工具就讓我去了解 Swagger-ui 生成文件介面，為什麼公司用的好好的想換一個而不影響原有的生成介面文件外掛

C# 新增文字、圖片到PDF文件（基於Spire.Cloud.PDF.SDK）

Spire.Cloud.PDF.SDK提供了介面PdfTextApi及PdfImagesApi用於新增文字和圖片到PDF文件，新增文字時，可格式化文字樣式，包括文字字型型別、字號、字型樣式、文字顏色、字元間距、行距、首行縮排、文字對齊方式、文字

ASP.NET Core Web API官方文件（連結）

下面這篇微軟官方文件，介紹了構建ASP.NET Core Web API的一些細節： Create web APIs with ASP.NET Core

DRF框架生成介面文件

一、簡介 生成API文件平臺 自動生成測試程式碼 支援介面測試 二、安裝 coreapi（必須）

ASP.NET Core 3.1使用Swagger API介面文件

Swagger是最流行的API開發工具，它遵循了OpenAPI規範，可以根據API介面自動生成線上文件，這樣就可以解決文件更新不及時的問題。它可以貫穿於整個API生態，比如API的設計、編寫API文件等。而且Swagger還是一種通用的

.NetCore學習筆記：六、Swagger API介面文件工具

Swagger一個優秀的Api介面文件生成工具。Swagger可以可以動態生成Api介面文件，有效的降低前後端人員關於Api介面的溝通成本，促進專案高效開發。

Swagger --Api介面文件

前後端分離，後臺負責寫介面。隨著介面越來越多，介面清單越來越重要，傳統是需要自己去維護一個doc的文件或者公司統一放在一個介面清單的web服務上。每次開發者需要單獨新增上去。修改後還需要維護。現接入swagger，

ColorUI文件（更新中）

1.開始 　　下載原始碼解壓獲得/Colorui-UniApp資料夾，複製目錄下的/colorui資料夾到你的專案根目錄