swagger 修改dto注解_Swagger 详解
Swagger快速理解
Swagger:The Best APIs are Built with Swagger Tools 。Swagger可以定義一個(gè)標(biāo)準(zhǔn)的RESTful風(fēng)格的API，與語言無關(guān)，是一個(gè)API的規(guī)范。
Swagger官網(wǎng)：http://swagger.io
GitHub地址：https://github.com/swagger-api
這里，提到Swagger就不得不說說Springfox,Springfox是一個(gè)開源的API Doc的框架， 它的前身是swagger-springmvc，可以將我們的Controller中的方法以文檔的形式展現(xiàn)。官方定義為： Automated JSON API documentation for API's built with Spring。Swagger和SpringFox到底什么關(guān)系呢？
- Swagger Spec 是一個(gè)規(guī)范。
- Swagger Api 是 Swagger Spec 規(guī)范 的一個(gè)實(shí)現(xiàn)，它支持 jax-rs, restlet, jersey 等等。
- Springfox libraries 是 Swagger Spec 規(guī)范 的另一個(gè)實(shí)現(xiàn)，專注于 spring 生態(tài)系統(tǒng)。
- Swagger.js and Swagger-ui 是 javascript 的客戶端庫，能消費(fèi)該規(guī)范。
- springfox-swagger-ui 僅僅是以一種方便的方式封裝了 swagger-ui ，使得 Spring 服務(wù)可以提供服務(wù)。
在官網(wǎng)的Tools菜單中，我們會(huì)發(fā)現(xiàn)里面有很多工具或者系統(tǒng)的介紹。其中我們最常用的兩個(gè)工具一個(gè)是swagger editor、一個(gè)是swagger UI。
Swagger Edit
Swagger Edit主要是用來設(shè)計(jì)，描述API的工具，主要是提供給接口開發(fā)人員使用的。swagger editor 編譯完接口文檔之后呢，會(huì)形成一個(gè)yaml文件。
Swagger UI
Swagger UI允許任何人 - 無論是您的開發(fā)團(tuán)隊(duì)還是最終消費(fèi)者 - 在沒有任何實(shí)現(xiàn)邏輯的情況下可視化和與API資源交互。 它是從您的OpenAPI規(guī)范自動(dòng)生成的，其可視化文檔使后端實(shí)現(xiàn)和客戶端消費(fèi)變得容易。
swagger-editor主要是編寫api接口文檔，但需要配合swagger-ui來查看，里面的代碼格式為yaml，但編輯后可以導(dǎo)出yml/json文件
Swagger Edit和Swagger UI 互補(bǔ)性存在
如果只是手動(dòng)寫api文檔，人工查看那么就做部署Swagger Edit和Swagger UI就可以了。
通過下面命令下載兩個(gè)項(xiàng)目：
mkdir swagger
chmod 777 swagger
cd swagger
git clone https://github.com/swagger-api/swagger-editor.git
git clone https://github.com/swagger-api/swagger-ui.git
PS: UI和Edit都是NodeJS的開發(fā)，一次需要先安裝Nodejs的運(yùn)行環(huán)境。
下載nodejs的安裝包，具體要去網(wǎng)站上查看最新版本
wget https://nodejs.org/dist/v6.11.3/node-v6.11.3.tar.gz
tar -zxvf node-v6.11.3.tar.gz
mv node-v6.11.3 /user/local/node
cd /usr/local/node
./configure
make
make install
node -v
先安裝http-server
npm install -g http-server
-g表示全局
啟動(dòng)ui和edit
http-server –p 12321 swagger-editor
http-server –p 12421 swagger-ui
cd swagger-ui/dist
vim index.html
進(jìn)入index.html后，修改如下字段
...
const ui = SwaggerUIBundle({
//url: "http://petstore.swagger.io/v2/swagger.json",
url: "http://127.0.0.1:12321/json/1.json",
dom_id: '#swagger-ui',
...
然后保存后
打開瀏覽器：
swaggerEdit ： http://127.0.0.1：12321
swaggerUI：http://127.0.0.1：12421/dist
Maven插件在原生工程里面快速生產(chǎn)Json的api文件(轉(zhuǎn)自：https://blog.csdn.net/doctor_who2004/article/details/50816208)
在maven工程的pom文件中，放入如下插件：
org.apache.maven.plugins
maven-javadoc-plugin
UTF-8
UTF-8
false
com.github.kongchen
swagger-maven-plugin
false
com.doctor.demo
http,https
petstore.swagger.wordnik.com
/api
Swagger Maven Plugin Sample
v1
This is a sample for swagger-maven-plugin
http://www.github.com/kongchen/swagger-maven-plugin
kongchen@gmail.com
Kong Chen
http://kongch.com
http://www.apache.org/licenses/LICENSE-2.0.html
Apache 2.0
Support classpath or file absolute path here. 1) classpath e.g: "classpath:/markdown.hbs", "classpath:/templates/hello.html" 2) file e.g: "${basedir}/src/main/resources/markdown.hbs", "${basedir}/src/main/resources/template/hello.html"
${basedir}/templates/strapdown.html.hbs
${basedir}/generated/document.html
generated/swagger-ui
compile
generate
Swagger和SpringMVC項(xiàng)目的整合(轉(zhuǎn)自：https://www.cnblogs.com/jtlgb/p/6734177.html)
引入依賴
com.mangofactory
swagger-springmvc
1.0.2
com.mangofactory
swagger-models
1.0.2
com.wordnik
swagger-annotations
1.3.11
com.google.guava
guava
15.0
com.fasterxml.jackson.core
jackson-annotations
2.4.4
com.fasterxml.jackson.core
jackson-databind
2.4.4
com.fasterxml.jackson.core
jackson-core
2.4.4
com.fasterxml
classmate
1.1.0
Swagger配置
Swagger的配置實(shí)際上就是自定義一個(gè)Config類，通過java編碼的方式實(shí)現(xiàn)配置。代碼如下：
import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
import com.mangofactory.swagger.models.dto.ApiInfo;
import com.mangofactory.swagger.plugin.EnableSwagger;
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
/**
* Created by xiaohui on 2016/1/14.
*/
@Configuration
@EnableSwagger
@EnableWebMvc
public class SwaggerConfig {
private SpringSwaggerConfig springSwaggerConfig;
/**
* Required to autowire SpringSwaggerConfig
*/
@Autowired
public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig)
{
this.springSwaggerConfig = springSwaggerConfig;
}
/**
* Every SwaggerSpringMvcPlugin bean is picked up by the swagger-mvc
* framework - allowing for multiple swagger groups i.e. same code base
* multiple swagger resource listings.
*/
@Bean
public SwaggerSpringMvcPlugin customImplementation()
{
return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
.apiInfo(apiInfo())
.includePatterns(".*?");
}
private ApiInfo apiInfo()
{
ApiInfo apiInfo = new ApiInfo(
"My Apps API Title",
"My Apps API Description",
"My Apps API terms of service",
"My Apps API Contact Email",
"My Apps API Licence Type",
"My Apps API License URL");
return apiInfo;
}
}
在springmvc的配置文件中加入以下配置即可。
class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />
??到目前為止，我們已經(jīng)完成了對(duì)所有接口方法的掃描解析功能，那解析得到什么內(nèi)容呢？這需要我們自定義，自定義操作的對(duì)象就是接口方法。先看段代碼：
/**
* 根據(jù)用戶名獲取用戶對(duì)象
* @param name
* @return
*/
@RequestMapping(value="/name/{name}", method = RequestMethod.GET)
@ResponseBody
@ApiOperation(value = "根據(jù)用戶名獲取用戶對(duì)象", httpMethod = "GET", response = ApiResult.class, notes = "根據(jù)用戶名獲取用戶對(duì)象")
public ApiResult getUserByName(@ApiParam(required = true, name = "name", value = "用戶名") @PathVariable String name) throws Exception{
UcUser ucUser = ucUserManager.getUserByName(name);
if(ucUser != null) {
ApiResult<UcUser> result = new ApiResult<UcUser>();
result.setCode(ResultCode.SUCCESS.getCode());
result.setData(ucUser);
return result;
} else {
throw new BusinessException("根據(jù){name=" + name + "}獲取不到UcUser對(duì)象");
}
}
上述代碼是Controller中的一個(gè)方法，@ApiOperation注解對(duì)這個(gè)方法進(jìn)行了說明，@ApiParam注解對(duì)方法參數(shù)進(jìn)行了說明。關(guān)于這兩個(gè)注解的使用，可以參看源碼。這樣子，Swagger就可以掃描接口方法，得到我們自定義的接口說明內(nèi)容。
說明： 其中@ApiOperation和@ApiParam為添加的API相關(guān)注解，個(gè)參數(shù)說明如下： @ApiOperation(value = “接口說明”, httpMethod = “接口請(qǐng)求方式”, response = “接口返回參數(shù)類型”, notes = “接口發(fā)布說明”；其他參數(shù)可參考源碼； @ApiParam(required = “是否必須參數(shù)”, name = “參數(shù)名稱”, value = “參數(shù)具體描述”
Swagger-UI配置
Swagger掃描解析得到的是一個(gè)json文檔，對(duì)于用戶不太友好。下面介紹swagger-ui，它能夠友好的展示解析得到的接口說明內(nèi)容。
從https://github.com/swagger-api/swagger-ui 獲取3.0版本以下，2.0版本以上。其所有的 dist 目錄下東西放到需要集成的項(xiàng)目里，本文放入 src/main/webapp/WEB-INF/swagger/ 目錄下。
修改swagger/index.html文件，默認(rèn)是從連接http://petstore.swagger.io/v2/swagger.json獲取 API 的 JSON，這里需要將url值修改為http://{ip}:{port}/{projectName}/api-docs的形式，{}中的值根據(jù)自身情況填寫。比如我的url值為：http://localhost:8083/arrow-api/api-docs
因?yàn)閟wagger-ui項(xiàng)目都是靜態(tài)資源，restful形式的攔截方法會(huì)將靜態(tài)資源進(jìn)行攔截處理，所以在springmvc配置文件中需要配置對(duì)靜態(tài)文件的處理方式。
//所有swagger目錄的訪問，直接訪問location指定的目錄
<mvc:resources mapping="/swagger/**" location="/WEB-INF/swagger/"/>
?OK！大功告成，打開瀏覽器直接訪問swagger目錄下的index.html文件，即可看到接口文檔說明了
是選擇SwaggerUI+EDIT方式還是SpringMVC直接集成，就看你自己的需求了
參考：
https://blog.csdn.net/kinginblue/article/details/78513029 https://www.jianshu.com/p/52acab692a79 https://blog.csdn.net/doctor_who2004/article/details/50816208 https://www.cnblogs.com/jtlgb/p/6734177.html
關(guān)注V社北京社，跟蹤測試行業(yè)技術(shù)
總結(jié)
以上是生活随笔為你收集整理的swagger 修改dto注解_Swagger 详解的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： 安卓10省电还是费电_iOS 13省电教
- 下一篇： 积木赛尔号机器人_【金福利】8月2日赛尔