使用swagger創建功能強大的API

wagger是什麼？swagger官網對其的簡介爲：Swagger is the world’s largest framework of API developer tools for the OpenAPI Specification(OAS), enabling development across the entire API lifecycle, from design and documentation, to test and deployment.從中我們可以看到，swagger符合OpenAPI的世界上最流行的API開發工具，它可以跨越API的整個生命週期，從設計到文檔，到測試到部署。簡單來說，swagger就是一款api生成工具，能夠幫助我們構建功能強大的API，我們可以使用swagger來進行測試等等。

下面我們來動手實現一個簡單的swagger工程。

爲了方便快速，直接新建一個spring boot工程，起名爲Swagger。spring boot就是一種簡化了的spring的使用方式。不瞭解spring boot的可以自行百度。如果使用MyEclipse或者TST，IDEA等開發工具，可以直接new->Spring Starter Project.使用Eclipse的可以到spring-boot官網上直接生成項目，然後導入工程。spring-boot項目生成地址：https://start.spring.io/。新建工程時在dependency導航時只需選擇web即可。如下：

在更目錄下創建controller包和domain包。

項目建成後，我們的項目結構看起來大概是這樣的：

在pom中加入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>

在controller下創建SwaggerController.java文件。其中用到的一些註解就不詳細解釋了，稍微懂點英文的一看就懂。不懂的做完這個demo後看到效果也會懂了。

package com.example.demo.controller;
import java.util.HashMap;
import java.util.Map;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import com.alibaba.fastjson.JSONObject;
import com.example.demo.domain.Student;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
@RestController
@RequestMapping("/students")
public class SwaggerController {
private static Map<String, Student> students=new HashMap<String, Student>();
@ApiOperation(value="加入一個學生",notes="根據提交的信息加入一個學生")
@ApiImplicitParam(name="student",value="要增加的學生信息",required=true,dataType="Student")
@RequestMapping(value="addStudent",method=RequestMethod.POST)
public String addStudent(@RequestBody Student student){
students.put(student.getStId(), student);
return "add student to students successfully";
}
@RequestMapping(value="/removeStudent/{stId}",method=RequestMethod.DELETE)
@ApiImplicitParam(name="id",required=true,dataType="String")
@ApiOperation(value="刪除一個學生",notes="根據學生id刪除學生")
public String removeStudent(@PathVariable("stId") String stId){
students.remove(stId);
return "remove student from students successfully";
}
@RequestMapping(value={""},method=RequestMethod.GET)
@ApiOperation(value="獲取學生列表",notes="獲取所有學生列表")
public String getAllStudent(){
return JSONObject.toJSONString(students);
}
}

在domain下面創建Student.java(省略getter/setter)

public class Student {
private String stId;
private String name;
private String height;
private String weight;

}

在SwaggerApplication.java的同級目錄下面新建一個SwaggerConfig.java用來配置Swagger的相關信息。

package com.example.demo;
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 SwaggerConfig {
@Bean
public Docket getAPIDocket(){ //創建Swagger容器
return new Docket(DocumentationType.SWAGGER_2)//設置文檔類型
.apiInfo(apiInfo())//api的相關描述信息，通常顯示在頁面的最上方
.select()//返回一個ApiSelectorBuilder，用來構建api容器
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))//設置掃描的包
.paths(PathSelectors.any())//設置掃描那些controller，這裏設置掃描全部，可以傳入正則表達式
.build();//構建api容器
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("張旭升")//標題
.description("使用swagger生成功能強大的API")//描述
.contact("張旭升")//聯繫信息
.version("1.0")//版本，除此之外還可以設置服務條款，license等信息。
.build();
}
}