1评甜、swagger學習
Swagger定義
Swagger同類工具
Swagger和web項目結(jié)合
Swagger在公司項目中如何應(yīng)用
2、Swagger定義
- Swagger官網(wǎng)：http://swagger.io
- GitHub地址：https://github.com/swagger-api
- 官方注解文檔：http://docs.swagger.io/swagger-core/apidocs/index.html
- Swagger-UI地址：https://github.com/swagger-api/swagger-ui
- 概念：
A Powerful Interface to your API
Swagger 是一個規(guī)范和完整的框架仔涩，用于生成忍坷、描述、調(diào)用和可視化 RESTful 風格的 Web 服務(wù)熔脂∨逖校總體目標是使客戶端和文件系統(tǒng)作為服務(wù)器以同樣的速度來更新。文件的方法霞揉，參數(shù)和模型緊密集成到服務(wù)器端的代碼旬薯，允許API來始終保持同步。 Swagger 讓部署管理和使用功能強大的API從未如此簡單适秩。
2.1 Swagger子項目
Swagger子項目
其實swagger是一個比較大的項目绊序，就像spring一樣，他下面有很多模塊秽荞，我們現(xiàn)在只需要使用它的UI模骤公。
3、相關(guān)學習博客
- 在線Demo: http://petstore.swagger.io
- swagger學習分享： http://www.mamicode.com/info-detail-525592.html
- InfoQ視頻：http://www.infoq.com/cn/presentations/use-swagger-create-rest-api-document?utm_source=tuicool&utm_medium=referral
- < http://hao.jobbole.com/swagger/>
- Swagger文檔： http://www.scalatra.org/2.2/guides/swagger.html
- swagger博客-：http://ningandjiao.iteye.com/blog/1948874
- swagger博客二： http://www.reibang.com/p/0465a2b837d2
- Swagger博客三： http://javatech.wang/index.php/archives/74/
- Swagger案例: http://petstore.swagger.io/#!/user/createUser
4扬跋、swagger和springmvc整合
4.1 依賴管理
<!-- swagger-mvc -->
<dependency>
<groupId>com.mangofactory</groupId>
<artifactId>swagger-springmvc</artifactId>
<version>1.0.2</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.4.2</version>
</dependency>
<!-- swagger-mvc -->
4.2 Swagger配置
Swagger的配置最終就是配置一個config類阶捆，通過Java編碼的方式實現(xiàn)配置：
@Configuration
@EnableSwagger
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;
}
}
這個是個模板，里面內(nèi)容可以自己定義钦听，修改基本上是對apiinfo自定義數(shù)據(jù)洒试。
在spring中注入Bean：
<context:component-scan base-package="net.shopin.swagger"/>
swagger基本就算是配置好了，剩下的事情就是接口編寫和展示了彪见。
引入swagger-UI組件
更改項目文檔路徑
更改項目文檔路徑
修改index.html文件中的路徑：默認是從連接http://petstore.swagger.io/v2/swagger.json獲取API的JSON,我們改為 http://{ip}:{port}/{projectName}/api-docs 的形式儡司，也就ip:端口號/項目名/api-docs
配置Xml
最后就是對controller的書寫：
@Api(value = "product", description = "商品管理", produces = MediaType.APPLICATION_JSON_VALUE)
@Controller
public class ProductController {
@Autowired
private ProductService productService;
@ApiOperation(value = "獲得商品信息", notes = "獲取商品信息(用于數(shù)據(jù)同步)", httpMethod = "POST", produces=MediaType.APPLICATION_JSON_VALUE)
@ApiResponses(value = {@ApiResponse(code = 200, message = "商品信息"),
@ApiResponse(code = 201, message = ErrorType.errorCheckToken + "(token驗證失敗)", response=String.class),
@ApiResponse(code = 202, message = ErrorType.error500 + "(系統(tǒng)錯誤)",response = String.class)})
@RequestMapping(value = RestUrl.getProduct, method = RequestMethod.POST)
@ResponseBody
public ResultDTO<Products> getProduct(@ApiParam(value = "json參數(shù)", required = true) @RequestBody BaseParam param)throws Exception {
return productService.getProduct(param);
}
}
當然你還需要是配置XML
ぐl(fā)ovefor丶 11:21:08
<!-- swagger 集成-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
配置XML的文件
- @API：表示一個開放的API，可以通過description簡明的描述API的功能余指，produce指定API的mime類型
- 一個@API下，可以有多個@ApiOperation,表示針對該API的CRUD操作跷坝，在ApiOperation Annotation中還可以通過value酵镜，notes描述該操作的作用，response描述正常情況下該請求返回的對象類型
- 在一個@ApiOperation下柴钻，可以通過@ApiResponses描述API操作可能出現(xiàn)的異常情況
- @ApiParam用于描述該API操作接收的參數(shù)類型淮韭，value用于描述參數(shù)，required指明參數(shù)是否為必須贴届。
- @ApiModelProperty中靠粪，value指定描述蜡吧，required指明是否為必須
代碼效果
WechatIMG1153.png
實現(xiàn)效果
WechatIMG1156.png
備注:
