據說微信搜索《Java魚仔》會變動強！html
本文收錄於JavaStarter ，裏面有我完整的Java系列文章，學習或面試均可以看看哦前端
（一）引言
個人第一份工做用的技術架構比較老，在寫Api接口的時候都是本身手動寫一個接口文檔。可是一旦接口多了，這些文檔就很難管理。我如今的工做在應用層面使用了SpringBoot，項目中也大量用到了Swagger2。我我的感受Swagger的厲害之處在於極少的配置和幾個註解就能夠生成一份完善的技術文檔，將維護文檔和修改代碼整合爲一體，節省了大量時間。java
（二）Swagger與SpringBoot的整合
Swagger的使用很簡單，這裏經過一個簡單的例子進行展現git
（2.1）引入依賴
先須要建立一個Springboot項目，並引入Swagger2的相關依賴：github
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
(2.2)建立實體類
由於項目比較簡單，實現User類的增刪改查API接口，所以所有放在一個文件夾之下，建立User.java，這裏用到了swagger對於實體類的兩個註解@ApiModel和@ApiModelProperty，分別表示實體類的含義以及屬性的含義。面試
@Data
@ApiModel("用戶實體類")
public class User {
@ApiModelProperty("id")
private Long id;
@ApiModelProperty("name")
private String name;
@ApiModelProperty("age")
private Integer age;
}
(2.3)建立Swagger2配置文件
swagger的配置主要基本的展現信息以及掃描信息，其中@Configuration註解使得Spring啓動該配置類，@EnableSwagger2啓動Swagger2spring
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
//建立api基本信息
.apiInfo(apiInfo())
.select()
//RequestHandlerSelectors.basePackage指定掃描的包路徑
//RequestHandlerSelectors.any():掃描所有
//RequestHandlerSelectors.none():不掃描
//RequestHandlerSelectors.withClassAnnotation():掃描類上的註解
//RequestHandlerSelectors.withMethodAnnotation():掃描方法上的註解
.apis(RequestHandlerSelectors.basePackage("com.javayz.swaggerdemo.controller"))
//過濾什麼路徑
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Java魚仔的SwaggerAPI文檔")
.description("你會累由於你在走上坡路")
.termsOfServiceUrl("https://blog.csdn.net/qq_41973594")
.contact(new Contact("Java魚仔","https://blog.csdn.net/qq_41973594","974474148@qq.com"))
.version("1.0")
.build();
}
}
ApiInfo中的參數以下所示：api
（2.4）建立Controller，定義API
@Api(value = "用戶信息管理")
@RestController
@RequestMapping(value="/users")
public class UserController {
//建立一個線程安全的map
static Map<Long, User> users = Collections.synchronizedMap(new HashMap<Long, User>());
//獲取User列表
@ApiOperation(value="獲取用戶列表", notes="")
@RequestMapping(value={""}, method= RequestMethod.GET)
public List<User> getUserList() {
List<User> r = new ArrayList<User>(users.values());
return r;
}
//根據用戶id刪除用戶
@ApiOperation(value = "刪除用戶",notes = "根據id刪除用戶")
@ApiImplicitParam(name = "id",value = "輸入用戶id",required = true,dataType = "Long")
@RequestMapping(value = "/{id}",method = RequestMethod.DELETE)
public String DeleteList(@PathVariable Long id){
users.remove(id);
return "success";
}
//建立用戶
@ApiOperation(value="建立用戶", notes="根據User對象建立用戶")
@ApiImplicitParam(name = "user", value = "用戶詳細實體user", required = true, dataType = "User")
@RequestMapping(value="", method=RequestMethod.POST)
public String postUser(@RequestBody User user) {
users.put(user.getId(), user);
return "success";
}
//根據用戶id獲取用戶信息
@ApiOperation(value="獲取用戶詳細信息", notes="根據url的id來獲取用戶詳細信息")
@ApiImplicitParam(name = "id", value = "用戶ID", required = true, dataType = "Long")
@RequestMapping(value="/{id}", method=RequestMethod.GET)
public User getUser(@PathVariable Long id) {
return users.get(id);
}
//根據指定id更新對象
@ApiOperation(value="更新用戶詳細信息", notes="根據url的id來指定更新對象，並根據傳過來的user信息來更新用戶詳細信息")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用戶ID", required = true, dataType = "Long"),
@ApiImplicitParam(name = "user", value = "用戶詳細實體user", required = true, dataType = "User")
})
@RequestMapping(value="/{id}", method=RequestMethod.PUT)
public String putUser(@PathVariable Long id, @RequestBody User user) {
User u = users.get(id);
u.setName(user.getName());
u.setAge(user.getAge());
users.put(id, u);
return "success";
}
}
以上代碼乍一看有不少的配置文件，其實實際使用起來很簡單，經過@Api、@ApiOperation註解來給API增長說明、經過@ApiImplicitParams、@ApiImplicitParam註解來給參數增長說明。註解各個參數的功能以下：瀏覽器
@Api：用在請求的類上，表示對類的說明
tags="說明該類的做用，能夠在UI界面上看到的註解"
value="該參數沒什麼意義，在UI界面上也看到，因此不須要配置"
@ApiOperation：用在請求的方法上，說明方法的用途、做用
value="說明方法的用途、做用"
notes="方法的備註說明"
@ApiImplicitParams：用在請求的方法上，表示一組參數說明
@ApiImplicitParam：用在@ApiImplicitParams註解中，指定一個請求參數的各個方面
name：參數名
value：參數的漢字說明、解釋
required：參數是否必須傳
paramType：參數放在哪一個地方
· header --> 請求參數的獲取：@RequestHeader
· query --> 請求參數的獲取：@RequestParam
· path（用於restful接口）--> 請求參數的獲取：@PathVariable
· body（不經常使用）
· form（不經常使用）
dataType：參數類型，默認String，其它值dataType="Integer"
defaultValue：參數的默認值
@ApiResponses：用在請求的方法上，表示一組響應
@ApiResponse：用在@ApiResponses中，通常用於表達一個錯誤的響應信息
code：數字，例如400
message：信息，例如"請求參數沒填好"
response：拋出異常的類
@ApiModel：用於響應類上，表示一個返回響應數據的信息
（這種通常用在post建立的時候，使用@RequestBody這樣的場景，
請求參數沒法使用@ApiImplicitParam註解進行描述的時候）
@ApiModelProperty：用在屬性上，描述響應類的屬性
（三）運行項目
完成所有代碼以後，啓動SpringBoot項目，在瀏覽器上輸入 http://localhost:8080/swagger-ui.html ，就能看到RESTful API接口界面安全
這個界面中能夠直接測試接口，每次代碼修改也都會同步到接口文檔中。咱們只須要把這個路徑發給前端同窗就大功告成了。
（四）總結
框架的目的是爲了簡化咱們的開發，合理利用框架可讓咱們的效率翻倍。我是魚仔，咱們下期再見。