java spring swagger

API工具框架Swagger 快速入門

王弼甫 2018/12/25 16:17:14
464

API工具框架Swagger 快速入門


簡介

Swagger能解決為 API 產生文件與說明頁面,還可以提供如互動式介面增加API測試效率

作者

王弼甫


1.前言

開發API時,花費的大量的時間在撰寫文件上,今天介紹的Swagger

能解決為 API 產生文件與說明頁面的問題

可以提供如互動式介面增加API測試效率

2. 環境

     IDE: IntelliJ IDEA 2018.1
     JDK: 1.8
     Framework: Spring-boot.1.5.10.RELEASE
     Build Tool: Maven 3
     Server: tomcat8
 
 

3.實作

 
1.首先在maven專案 pom.xml增加
    springfox-swagger2 是我們主要要使用的套件
    springfox-swagger-ui 是有HTML UI介面方便在WEB上操作
<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.接著制定一個學生資料的物件 Student.java
   下面這些annotation註釋是在Swagger UI介面中會自動生成API文件方便查看
 
@ApiModel
    描述此Model的名稱
 
@ApiModelProperty
    描述此Model裡各屬性名稱,後面的required代表是否為必填參數
@ApiModel(description = "學生資料")
public class Student {

@ApiModelProperty(value = "學生姓名",required = true)
private String name;

@ApiModelProperty(value = "學生編號",required = true)

private Integer no;

@ApiModelProperty(value = "學生年齡",required = true)

private Integer age;

public String getName() {

return name;
}


public void setName(String name) {
this.name = name;
}


public Integer getNo() {
return no;
}


public void setNo(Integer no) {
this.no = no;
}


public Integer getAge() {
return age;
}


public void setAge(Integer age) {
this.age = age;
}
 
3.接著我們撰寫一個新增、查詢、刪除的Controller.java
 
@ApiResponses
   
    如果需要自訂Response Code和Message,我們可以在這自行定義
   

@ApiOperation

    用在API上,代表此API的名稱或作用

其他用法可參考以下網址

https://hk.saowen.com/a/84e86300f9c93433dfd72b14a1fa142ce1a5356185f5c28ed40dcfc440d6a2da


@RestController
public class BaseController {


@Autowired
private StudentService studentService;

@ApiResponses(value = {@ApiResponse(code=200,message = "查詢成功")})

@ApiOperation("查詢學生")
@GetMapping(value = "/getStudent/{no}",produces = {MediaType.APPLICATION_JSON_VALUE})
public Student getStudent(@PathVariable int no) {
return studentService.getStudentByNo(no);
}



@ApiResponses(value = {@ApiResponse(code=200,message = "新增成功")})
@ApiOperation("新增學生")
@PostMapping(value = "/addStudent",consumes = MediaType.APPLICATION_JSON_VALUE,produces = MediaType.APPLICATION_JSON_VALUE)
public Student addStudent(@RequestBody Student student) {
return studentService.addStudent(student);
}


@ApiResponses(value = {@ApiResponse(code=200,message = "查詢成功")})
@ApiOperation("取得所有學生")
@GetMapping(value = "/getAllStudent",consumes = MediaType.APPLICATION_JSON_VALUE,produces = MediaType.APPLICATION_JSON_VALUE)
public List<Student> getAllStudents(){
return studentService.getAllStudent();
}


@ApiResponses(value = {@ApiResponse(code=200,message = "刪除成功")})
@ApiOperation("刪除學生")
@GetMapping(value = "/delStudent/{no}",produces = {MediaType.APPLICATION_JSON_VALUE})
public void delStudent(@PathVariable int no){
studentService.delStudent(no);
}


}
 
4.接著寫一個 swagger的配置檔 SwaggerConfig.java
@Configuration
@EnableSwagger2
public class SwaggerConfig {


@Bean
public Docket api(){

return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
.paths(PathSelectors.any())
.build();
}


}

 

5.最後啟動服務,進入http://localhost:8080/swagger-ui.html,就能進入swegger的UI介面

 

6.可以點選各API,就可以直接看到各API 需要Request和回應Response的資料

 

7.點選右上角的Try It Out按鈕,會直接產出Example Value,就可以直接輸入需要參數測試API是否正常。

 

8. 按下Excute,結果就會顯示在下方

王弼甫