知識星球（點選上方公眾號，可快速關註）
來源：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
foo( @ApiParam(value = “使用者名稱”, required = true) @RequestParam String name,
@ApiParam(value = “年齡”, required = true) @RequestParam String age
) {
//獲取請求的引數，需要和連結中的引數名一致
//推薦使用HttpServletRequest的方式來獲取引數，GET、POST的引數都可以接收
List
list = new ArrayList ();
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的依賴：
com.mangofactory
swagger-springmvc
1.0.2
（6）完成後的執行介面如下圖所示。大家可以根據自己的實際需求自定義頁面元素。
看完本文有收穫？請轉發分享給更多人
關註「ImportNew」，提升Java技能
