javascript
swagger2maven依赖_Maven + SpringMVC项目集成Swagger
Swagger 是一個規范和完整的框架，用于生成、描述、調用和可視化 RESTful 風格的 Web 服務。總體目標是使客戶端和文件系統作為服務器以同樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，允許API來始終保持同步。
作用：
接口的文檔在線自動生成。
功能測試。
下面通過實現一個web項目來演示Swagger的使用。
1. 新建SpringMVC項目
1.1 新建項目
新建基于maven的web項目，導入spring相關依賴如下
4.0.0
com.zang.xz
mySwagger
0.0.1-SNAPSHOT
war
mySwagger Maven Webapp
http://www.example.com
UTF-8
4.3.6.RELEASE
com.fasterxml.jackson.core
jackson-databind
2.8.9
org.springframework
spring-core
${spring.framework.version}
org.springframework
spring-context
${spring.framework.version}
org.springframework
spring-webmvc
${spring.framework.version}
mySwagger
1.2 配置web.xml和spring-mvc.xml
web.xml
Archetype Created Web Application
spring-mvc
org.springframework.web.servlet.DispatcherServlet
contextConfigLocation
classpath:spring-mvc.xml
1
true
spring-mvc
/
encodingFilter
org.springframework.web.filter.CharacterEncodingFilter
encoding
UTF-8
forceEncoding
true
encodingFilter
/*
spring-mvc.xml
http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-4.0.xsd
http://www.springframework.org/schema/mvc http://www.springframework.org/schema/mvc/spring-mvc-4.0.xsd">
1.3 新建entity和controller測試
為求簡便，這里不集成dao層，數據直接從controller中封裝返回。
Product.java
packagecom.zang.xz.entity;public classProduct {private static final long serialVersionUID = 1L;/**ID*/
privateLong id;/**產品名稱*/
privateString name;/**產品型號*/
privateString productClass;/**產品ID*/
privateString productId;publicLong getId() {returnid;
}public voidsetId(Long id) {this.id =id;
}publicString getName() {returnname;
}public voidsetName(String name) {this.name =name;
}publicString getProductClass() {returnproductClass;
}public voidsetProductClass(String productClass) {this.productClass =productClass;
}publicString getProductId() {returnproductId;
}public voidsetProductId(String productId) {this.productId =productId;
}
@OverridepublicString toString() {return "Product [id=" + id + ", name=" + name + ", productClass="
+ productClass + ", productId=" + productId + "]";
}
}
ProductController.java
packagecom.zang.xz.controller;importjava.util.Arrays;importjava.util.List;importorg.springframework.http.ResponseEntity;importorg.springframework.web.bind.annotation.PathVariable;importorg.springframework.web.bind.annotation.RequestMapping;importorg.springframework.web.bind.annotation.RequestMethod;importorg.springframework.web.bind.annotation.RestController;importcom.zang.xz.entity.Product;
@RestController
@RequestMapping(value= {"/product/"})public classProductController {
@RequestMapping(value= "/{id}", method =RequestMethod.GET)public ResponseEntityget(@PathVariable Long id) {
Product product= newProduct();
product.setName("空氣凈化器");
product.setId(1L);
product.setProductClass("filters");
product.setProductId("T12345");returnResponseEntity.ok(product);
}
}
測試
至此，創建了一個簡單的基于SpringMVC的Web項目，并能對外提供REST風格的API接口。接下來，我們要整合SpringFox和SwaggerUI到該SpringMVC項目中去，使其對外接口文檔化。
2. 集成Swagger
2.1 添加swagger相關jar包
io.springfox
springfox-swagger2
2.7.0
io.springfox
springfox-swagger-ui
2.7.0
此處swagger 的核心依賴使用springfox-swagger2，SpringFox已經可以代替swagger-springmvc, 目前SpringFox同時支持Swagger 1.2 和 2.0。
2.2 添加SwaggerConfig
packagecom.zang.xz.controller;importorg.springframework.context.annotation.Bean;importorg.springframework.context.annotation.Configuration;importspringfox.documentation.builders.ApiInfoBuilder;importspringfox.documentation.builders.RequestHandlerSelectors;importspringfox.documentation.service.ApiInfo;importspringfox.documentation.spi.DocumentationType;importspringfox.documentation.spring.web.plugins.Docket;importspringfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2public classSwaggerConfig {
@BeanpublicDocket api() {return newDocket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())//顯示所有類//.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))//只顯示添加@Api注解的類
.build()
.apiInfo(apiInfo());
}privateApiInfo apiInfo() {return newApiInfoBuilder()
.title("開放接口API") //粗標題
.description("HTTP對外開放接口") //描述
.version("1.0.0") //api version
.termsOfServiceUrl("http://xxx.xxx.com")
.license("LICENSE") //鏈接名稱
.licenseUrl("http://xxx.xxx.com") //鏈接地址
.build();
}
}
2.3 靜態資源訪問配置
上面引入的springfox-swagger-ui依賴為我們提供了靜態資源訪問的支持，通過訪問他為我們提供的頁面，可以直觀的看出項目所開放的接口API。
要想訪問該頁面，還需要增加訪問配置，方法有兩種：
2.3.1 在spring-mvc.xml中增加配置
2.3.2 或者增加配置類WebAppConfig
packagecom.zang.xz.controller;importorg.springframework.context.annotation.Configuration;importorg.springframework.web.servlet.config.annotation.EnableWebMvc;importorg.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;importorg.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
@Configuration
@EnableWebMvcpublic class WebAppConfig extendsWebMvcConfigurerAdapter {
@Overridepublic voidaddResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
3. 測試API接口
3.1 訪問“項目地址/swagger-ui.html#/”查看api
訪問 http://localhost:8090/mySwagger/swagger-ui.html#/出現如下界面，說明我們的swagger集成項目成功。
在參數中輸入信息，可實現對接口的調用
但是單調的頁面沒有實現swagger作為API文檔工具的作用，這需要我們通過注解在接口方法中配置。
3.2 通過注解生成API文檔
常用注解如下：
常用注解：
@Api()用于類；?表示標識這個類是swagger的資源
@ApiOperation()用于方法；?表示一個http請求的操作
@ApiParam()用于方法，參數，字段說明；?表示對參數的添加元數據(說明或是否必填等)
@ApiModel()用于類?表示對類進行說明，用于參數用實體類接收
@ApiModelProperty()用于方法，字段 ；表示對model屬性的說明或者數據操作更改
@ApiIgnore()用于類，方法，方法參數 ；表示這個方法或者類被忽略
@ApiImplicitParam()?用于方法 ；表示單獨的請求參數
@ApiImplicitParams()?用于方法，包含多個 @ApiImplicitParam
@RestController
@RequestMapping(value= { "/product/"})//類上加@Api注解
@Api(value = "/ProductController", tags = "接口開放示例")public classProductController {
@RequestMapping(value= "/{id}", method =RequestMethod.GET)//方法上加ApiOpreation注解
@ApiOperation(value = "根據id獲取產品信息", notes = "根據id獲取產品信息", httpMethod = "GET", response = Product.class)public ResponseEntityget(@PathVariable Long id) {
Product product= newProduct();
product.setName("空氣凈化器");
product.setId(1L);
product.setProductClass("filters");
product.setProductId("T12345");returnResponseEntity.ok(product);
}
}
添加注解之后，訪問swagger界面如下
3.3 其他方法測試
多增加幾個測試方法
@RequestMapping(method =RequestMethod.POST)
@ApiOperation(value= "添加一個新的產品")
@ApiResponses(value= { @ApiResponse(code = 405, message = "參數錯誤") })public ResponseEntityadd(Product product) {return ResponseEntity.ok("SUCCESS");
}
@RequestMapping(method=RequestMethod.PUT)
@ApiOperation(value= "更新一個產品")
@ApiResponses(value= { @ApiResponse(code = 400, message = "參數錯誤") })public ResponseEntityupdate(Product product) {return ResponseEntity.ok("SUCCESS");
}
@RequestMapping(method=RequestMethod.GET)
@ApiOperation(value= "獲取所有產品信息", notes = "獲取所有產品信息", httpMethod = "GET", response = Product.class, responseContainer = "List")public ResponseEntity>getAllProducts() {
Product product= newProduct();
product.setName("七級濾芯凈水器");
product.setId(1L);
product.setProductClass("seven_filters");
product.setProductId("T12345");returnResponseEntity.ok(Arrays.asList(product, product));
}
swagger界面為不同方法提供不同顏色顯示，可在其中對各個接口進行測試
項目結構如下：
總結
以上是生活随笔為你收集整理的swagger2maven依赖_Maven + SpringMVC项目集成Swagger的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： MFC CListCtrl 取消选中
- 下一篇： MySQL 视图的基础操作