https://mp.weixin.qq.com/s?__biz=MzU3NDYzMDQ5NA==&tempkey=OTYzX2UzZGRTY3RpclRMZW9zZHhHa0V4S0gwYXRzOE1ub1kyUE9rLW16MXAzb3Uwa2lySVJLdElpMFd0YkQySmVYT0ZrcExVajZueXl0YVdET0k1VGNub2R4RlM1RUhEcjh0MV9QM19ucjNPTkdtOFNReDhXYlFMUFUzdFJfNVNZYlpFZ2o1aHFoRFViX0JpVU8wOXZ2QUJIbU5zdzl4RmdQSnYwSDl2NHd%2Bfg%3D%3D&chksm=7d2e3ea14a59b7b76057529b6aa5037cfa2355532390a79d328c24dbcb607c4dd8b71d32a356&mpshare=1&scene=1&srcid=0701XeAFZifoozex6l1NfzZ2#wechat_redirect
01
引入依赖
SpringBoot
在创建一个简单的springboot项目后，首先要引入swagger的Maven依赖。
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.springboot.learning</groupId>
<artifactId>springboot-swagger</artifactId>
<version>0.0.1-SNAPSHOT</version>
<description>springboot集成swagger2构建RESTful API</description>
<developers>
<developer>
<name>wangxiaojie</name>
<email>[email protected]</email>
</developer>
</developers>
<!-- 引入springboot的父依赖 -->
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>1.5.4.RELEASE</version>
<type>pom</type>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
<version>1.5.4.RELEASE</version>
</dependency>
<!-- swagger依赖 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>
</dependencies>
</project>创建Swagger2的配置类
SpringBoot
在SpringBoot启动类的同级目录下创建Swagger2的配置类。
Swagger2配置类的具体信息如下：
package com.springboot;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket creatRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors
.basePackage("com.springboot.swagger"))
.paths(PathSelectors.any()).build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建RESTful APIs")
.description("更多文章请关注: 微信公众号：JavaCola ")
.termsOfServiceUrl("https://github.com/AbsolutelyEmpty")
.contact("大大蜡笔小小新").version("1.0").build();
}
}添加文档内容
SpringBoot
以上所有完成后，其实可以通过http://localhost:8080/swagger-ui.html访问接口文档。
但是这样的接口文档描述并不是很友好，基本都是基于方法名，Controller的类命名生成的，所以要通过注解对接口文档进行更为友好的提示与说明，需要在对应的接口方法上添加注解。
package com.springboot.swagger;
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 java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import com.springboot.model.CityModel;
@Api(value="城市信息管理服务")
@RequestMapping(value="/cities")
@RestController
public class CityController {
Map<String, Object> map = new HashMap<String, Object>();
CityModel cityModel = new CityModel("71000","西安","二线","9983平方公里");
List<CityModel> cityInfoList = new ArrayList<CityModel>();
{
String postCode = "71000";
map.put(postCode, cityModel);
}
@ApiOperation(value = "查询城市信息",notes = "通过邮政编码查询对应城市信息")
@ApiImplicitParam(name = "postCode",value = "所查询城市的邮政编码",required = true, dataType = "String", paramType="path")
@GetMapping(value = "/findCityInfo/{postCode}")
public CityModel findCityInfo(@PathVariable String postCode){
CityModel cityModel =(CityModel) map.get(postCode);
return cityModel;
}
@ApiOperation(value = "添加城市信息",notes = "添加城市信息")
@ApiImplicitParam(name = "cityModelInfo",value = "所添加城市的具体信息",required = true, dataType = "CityModel", paramType="body")
@ApiResponse(code = 200, message = "添加成功")
@PostMapping(value = "/addCityInfo")
public String addCityInfo(@RequestBody CityModel cityModelInfo){
cityInfoList.add(cityModelInfo);
return "SUCCESS";
}
@ApiOperation(value = "更新城市信息",notes = "根据邮政编码更新城市信息")
@ApiImplicitParams({
@ApiImplicitParam(name = "postCode", value = "邮政编码",required = true, dataType = "String", paramType = "path" ),
@ApiImplicitParam(name = "cityModel",value = "所添加城市的具体信息",required = true, dataType = "CityModel", paramType="body")})
@PutMapping(value = "/updateCityInfo/{postCode}/cityInfo")
public CityModel updateCityInfo(@PathVariable String postCode,@RequestBody CityModel cityModel){
CityModel cityUpdateModel =(CityModel) map.get(postCode);
cityUpdateModel.setCityLevel("一线");
return cityUpdateModel;
}
@ApiOperation(value = "删除城市信息",notes = "通过邮政编码删除对应城市信息")
@ApiImplicitParam(name = "postCode",value = "所删除城市的邮政编码",required = true, dataType = "String", paramType="path")
@ApiResponse(code = 200, message = "删除成功")
@DeleteMapping(value = "/deleteCityInfo/{postCode}")
public String deleteCityInfo(@PathVariable String postCode){
cityInfoList.add(cityModel);
cityInfoList.remove(0);
return "SUCCESS";
}
}注：其他的文档说明的注解很简单，基本自己可以学习一下。
这里需要说明的是@ApiImplicitParama中的paramType属性，具体的值对应如下：
qurery：对应@RequestParam的参数；
header：对应头部信息的参数；
path：对应url中的参数；
body：对应@RequestBody中的参数。
再次访问文档的访问地址：
http://localhost:8080/swagger-ui.html,
结果图如下，是不是更加简单明白。