swagger 修改dto注解_Swagger 详解
Swagger快速理解
Swagger:The Best APIs are Built with Swagger Tools 。Swagger可以定義一個標準的RESTful風格的API，與語言無關，是一個API的規范。
Swagger官網：http://swagger.io
GitHub地址：https://github.com/swagger-api
這里，提到Swagger就不得不說說Springfox,Springfox是一個開源的API Doc的框架， 它的前身是swagger-springmvc，可以將我們的Controller中的方法以文檔的形式展現。官方定義為： Automated JSON API documentation for API's built with Spring。Swagger和SpringFox到底什么關系呢？
- Swagger Spec 是一個規范。
- Swagger Api 是 Swagger Spec 規范 的一個實現，它支持 jax-rs, restlet, jersey 等等。
- Springfox libraries 是 Swagger Spec 規范 的另一個實現，專注于 spring 生態系統。
- Swagger.js and Swagger-ui 是 javascript 的客戶端庫，能消費該規范。
- springfox-swagger-ui 僅僅是以一種方便的方式封裝了 swagger-ui ，使得 Spring 服務可以提供服務。
在官網的Tools菜單中，我們會發現里面有很多工具或者系統的介紹。其中我們最常用的兩個工具一個是swagger editor、一個是swagger UI。
Swagger Edit
Swagger Edit主要是用來設計，描述API的工具，主要是提供給接口開發人員使用的。swagger editor 編譯完接口文檔之后呢，會形成一個yaml文件。
Swagger UI
Swagger UI允許任何人 - 無論是您的開發團隊還是最終消費者 - 在沒有任何實現邏輯的情況下可視化和與API資源交互。 它是從您的OpenAPI規范自動生成的，其可視化文檔使后端實現和客戶端消費變得容易。
swagger-editor主要是編寫api接口文檔，但需要配合swagger-ui來查看，里面的代碼格式為yaml，但編輯后可以導出yml/json文件
Swagger Edit和Swagger UI 互補性存在
如果只是手動寫api文檔，人工查看那么就做部署Swagger Edit和Swagger UI就可以了。
通過下面命令下載兩個項目：
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的開發，一次需要先安裝Nodejs的運行環境。
下載nodejs的安裝包，具體要去網站上查看最新版本
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表示全局
啟動ui和edit
http-server –p 12321 swagger-editor
http-server –p 12421 swagger-ui
cd swagger-ui/dist
vim index.html
進入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插件在原生工程里面快速生產Json的api文件(轉自：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項目的整合(轉自：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的配置實際上就是自定義一個Config類，通過java編碼的方式實現配置。代碼如下：
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" />
??到目前為止，我們已經完成了對所有接口方法的掃描解析功能，那解析得到什么內容呢？這需要我們自定義，自定義操作的對象就是接口方法。先看段代碼：
/**
* 根據用戶名獲取用戶對象
* @param name
* @return
*/
@RequestMapping(value="/name/{name}", method = RequestMethod.GET)
@ResponseBody
@ApiOperation(value = "根據用戶名獲取用戶對象", httpMethod = "GET", response = ApiResult.class, notes = "根據用戶名獲取用戶對象")
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("根據{name=" + name + "}獲取不到UcUser對象");
}
}
上述代碼是Controller中的一個方法，@ApiOperation注解對這個方法進行了說明，@ApiParam注解對方法參數進行了說明。關于這兩個注解的使用，可以參看源碼。這樣子，Swagger就可以掃描接口方法，得到我們自定義的接口說明內容。
說明： 其中@ApiOperation和@ApiParam為添加的API相關注解，個參數說明如下： @ApiOperation(value = “接口說明”, httpMethod = “接口請求方式”, response = “接口返回參數類型”, notes = “接口發布說明”；其他參數可參考源碼； @ApiParam(required = “是否必須參數”, name = “參數名稱”, value = “參數具體描述”
Swagger-UI配置
Swagger掃描解析得到的是一個json文檔，對于用戶不太友好。下面介紹swagger-ui，它能夠友好的展示解析得到的接口說明內容。
從https://github.com/swagger-api/swagger-ui 獲取3.0版本以下，2.0版本以上。其所有的 dist 目錄下東西放到需要集成的項目里，本文放入 src/main/webapp/WEB-INF/swagger/ 目錄下。
修改swagger/index.html文件，默認是從連接http://petstore.swagger.io/v2/swagger.json獲取 API 的 JSON，這里需要將url值修改為http://{ip}:{port}/{projectName}/api-docs的形式，{}中的值根據自身情況填寫。比如我的url值為：http://localhost:8083/arrow-api/api-docs
因為swagger-ui項目都是靜態資源，restful形式的攔截方法會將靜態資源進行攔截處理，所以在springmvc配置文件中需要配置對靜態文件的處理方式。
//所有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
關注V社北京社，跟蹤測試行業技術
總結
以上是生活随笔為你收集整理的swagger 修改dto注解_Swagger 详解的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： 安卓10省电还是费电_iOS 13省电教
- 下一篇： 积木赛尔号机器人_【金福利】8月2日赛尔