SpringMVC 開發 — 使用 Swagger 搭建介面請求頁面
（點擊
上方公眾號
，可快速關注）
來源：MSSQL123，
blog.csdn.net/chenyufeng1991/article/details/69201353
Swagger是一款RESTful介面的文檔在線自動生成模板和頁面，使用和平台以及語言無關。目前在很多公司以及實際項目中大量用到。可以把Swagger理解為介面文檔，後台寫好的代碼可以直接生成前端介面文檔頁面，介面調用這可以通過這個頁面發送介面請求，進行介面測試或調用。使用起來非常方便。使用了Swagger之後，就不需要再去維護其他的介面文檔了，節省了很多的成本。本文使用的項目案例上傳至 https://github.com/chenyufeng1991/StartSpringMVC.git 。本文將會來介紹如何搭建一個完整的Swagger框架。Swagger的官方地址為：http://swagger.io/。一個簡答的Swagger頁面如下圖所示：
（1）Swagger在Github上的地址為：https://github.com/swagger-api/swagger-ui 。大家可以下載該項目，然後把dist目錄下的所有內容都加入到自己項目的webapp目錄下。大家也可以下載我的StartSpringMVC項目，把webapp目錄下的css、images、lib、index.html和swagger-ui.js導入到自己的項目中即可。其中顯示的前端頁面就是index.html.
（2）然後需要在項目中新加一個類，作為swagger的配置文件，我在StartSpringMVC中的類是「CustomJavaPluginConfig」,該類的實現如下：
@Configuration
@EnableWebMvc
@EnableSwagger
public class CustomJavaPluginConfig extends WebMvcConfigurerAdapter {
private SpringSwaggerConfig springSwaggerConfig;
@Autowired
public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
this.springSwaggerConfig = springSwaggerConfig;
}
@Bean
public SwaggerSpringMvcPlugin customImplementation() {
return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
.apiInfo(apiInfo()).includePatterns(".*")
.useDefaultResponseMessages(false)
// .pathProvider(new GtPaths())
.apiVersion("0.1").swaggerGroup("user");
}
private ApiInfo apiInfo() {
ApiInfo apiInfo = new ApiInfo("我的RESTful介面平台",
"提供詳細的後台所有Restful介面", "http://blog.csdn.net/chenyufeng1991",
"yufengcode@gmail.com", "乞力馬扎羅的雪-博客", "http://blog.csdn.net/chenyufeng1991");
return apiInfo;
}
@Override
public void configureDefaultServletHandling(
DefaultServletHandlerConfigurer configurer) {
configurer.enable();
}
class GtPaths extends SwaggerPathProvider {
@Override
protected String applicationPath() {
return "/restapi";
}
@Override
protected String getDocumentationPath() {
return "/restapi";
}
}
}
（3）對於一個實體模型，需要使用swagger去標識。如下面的Student模型，其中的@ApiModel、@ApiModelProperty都是屬於Swagger的註解。如果需要在介面中返回模型對象，則需要使用以下的方式去註解。
@ApiModel(value = "學生對象", description = "student")
public class Student {
@ApiModelProperty(value = "姓名", required = true)
String name;
@ApiModelProperty(value = "年齡", required = true)
String age;
public Student(String name, String age) {
this.name = name;
this.age = age;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public String getAge() {
return age;
}
public void setAge(String age) {
this.age = age;
}
}
（4）在進行介面設計的Controller中，同樣需要使用Swagger註解。其中下面的@Api、@ApiOperaction、@Apiparam都是Swagger註解，其中@Api表示這是一個需要Swagger表示的類；@ApiOperaction表示這是一個需要Swagger修飾的介面，其中表明了請求方式、說明等信息。@ApiParam表示該介面輸入的參數，value是參數的值說明，required表示該參數是否是必須的。
@Api(value = "football", description = "足球", produces = MediaType.APPLICATION_JSON_VALUE)
@Controller
@RequestMapping("football")
public class FootballController {
@ApiOperation(value = "用戶登錄註冊", notes = "用戶", httpMethod = "GET", produces = MediaType.APPLICATION_JSON_VALUE)
@ResponseBody
@RequestMapping(value = "user", method = RequestMethod.GET)
public List<Student> foo(
@ApiParam(value = "用戶名", required = true) @RequestParam String name,
@ApiParam(value = "年齡", required = true) @RequestParam String age
) {
//獲取請求的參數，需要和鏈接中的參數名一致
//推薦使用HttpServletRequest的方式來獲取參數，GET、POST的參數都可以接收
List<Student> list = new ArrayList<Student>();
Student student = new Student(name, age);
Student student1 = new Student(name + name, age + age);
list.add(student);
list.add(student1);
return list;
}
@ApiOperation(value = "用戶登錄註冊2", notes = "用戶2", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
@ResponseBody
@RequestMapping(value = "customer/login", method = RequestMethod.POST)
public String foo2(
@ApiParam(value = "用戶名", required = true) @RequestParam String name
) {
return name;
}
}
（5）重要的是，要在pom.xml中加入swagger的依賴：
<!-- Swagger-mvc -->
<dependency>
<groupId>com.mangofactory</groupId>
<artifactId>swagger-springmvc</artifactId>
<version>1.0.2</version>
</dependency>
（6）完成後的運行界面如下圖所示。大家可以根據自己的實際需求自定義頁面元素。
看完本文有收穫？請轉發分享給更多人
關注「ImportNew」，提升Java技能
TAG:ImportNew |