# 使用 swagger.io 來建立符合OpenAPI規範的Restful API
- [GitHub位置](https://github.com/camioljoyce/springboot-Restful-Demo)

**首先按照之前做的這篇, 建立好基本的Restful API**
- [建立一個Restful API的專案](https://hackmd.io/iQp4KS1CTXWauL-EOdWXmg)

然後我們在POM檔加入Swagger 的Dependency

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

我們在原本的Entity的class這邊, 加上@ApiModel
在屬性上面,加上@ApiModelProperty

package camiol.example.com.entity;

import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import javax.persistence.Table;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@Entity
@Table(name = "Student")
@ApiModel(description = "學生資料")
public class Student {
	@Id
	@GeneratedValue(strategy = GenerationType.AUTO)
	@ApiModelProperty(value = "學號")
	private long id;
	
	@Column(name="Name")
	@ApiModelProperty(value = "姓名")
	private String name;
	
	@Column(name="Math_Score")
	@ApiModelProperty(value = "數學成績")
	private int mathScore;
	
	public long getId() {
		return id;
	}
	public void setId(long id) {
		this.id = id;
	}
	public String getName() {
		return name;
	}
	public void setName(String name) {
		this.name = name;
	}
	public int getMathScore() {
		return mathScore;
	}
	public void setMathScore(int mathScore) {
		this.mathScore = mathScore;
	}
	
}

然後在controller這邊,加上@Api和@ApiOperation和@ApiResponses

package camiol.example.com.controller;

import java.util.List;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import camiol.example.com.entity.Student;
import camiol.example.com.service.StudentService;
import camiol.example.com.vo.ResponseVo;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;

@Api(tags = "學生相關操作")
@RestController	
@RequestMapping(value = "/student", produces = "application/json")
public class StudentController {
	
	@Autowired
	private StudentService service;
	
	@ApiOperation(value = "取得指定學生資料" , notes = "取得指定學生資料")
	@ApiResponses({
		@ApiResponse(responseCode = "200" ,description = "成功"),
		@ApiResponse(responseCode = "404" ,description = "找不到網頁"),
		@ApiResponse(responseCode = "500" ,description = "其他錯誤")
	})
	@GetMapping("/get")
	public ResponseVo getStudent(@RequestParam("id") long id) {
		ResponseVo result = new ResponseVo();
		Student s = service.findById(id);
		if(s!=null) {
			result.setResult(s);
			result.setMessage("Query Success!");
			result.setRcode("0000");
		}else {
			result.setMessage("No Data!");
			result.setRcode("0301");
		}
		return result;
	}
	
	@ApiOperation(value = "取得所有學生資料" , notes = "取得所有學生資料" )
	@ApiResponses({
		@ApiResponse(responseCode = "200" ,description = "成功"),
		@ApiResponse(responseCode = "404" ,description = "找不到網頁"),
		@ApiResponse(responseCode = "500" ,description = "其他錯誤")
	})
	@GetMapping("/getAll")
	public ResponseVo getAllStudent() {
		ResponseVo result = new ResponseVo();
		List<Student> list = service.findAll();
		if(list!=null && !list.isEmpty()) {
			result.setResult(list);
			result.setMessage("Query Success!");
			result.setRcode("0000");
		}else {
			result.setMessage("No Data!");
			result.setRcode("0301");
		}
		return result;
	}
	
	@ApiOperation(value = "新增學生資料" , notes = "新增學生資料" )
	@ApiResponses({
		@ApiResponse(responseCode = "200" ,description = "成功"),
		@ApiResponse(responseCode = "404" ,description = "找不到網頁"),
		@ApiResponse(responseCode = "500" ,description = "其他錯誤")
	})
	@PostMapping("/add")
	public ResponseVo saveStudent(@RequestParam("name") String name,@RequestParam("mathScore") int mathScore) {
		ResponseVo result = new ResponseVo();
		Student s = new Student();
		s.setName(name);
		s.setMathScore(mathScore);
		service.saveOrUpdate(s);
		
		result.setMessage("Insert Success!");
		result.setRcode("0000");
		return result;
	}
	
	@ApiOperation(value = "更新學生資料" , notes = "更新學生資料" )
	@ApiResponses({
		@ApiResponse(responseCode = "200" ,description = "成功"),
		@ApiResponse(responseCode = "404" ,description = "找不到網頁"),
		@ApiResponse(responseCode = "500" ,description = "其他錯誤")
	})
	@PutMapping("/update")
	public ResponseVo updateStudent(@RequestParam("id") long id,@RequestParam("name") String name,@RequestParam("mathScore") int mathScore) {
		ResponseVo result = new ResponseVo();
		Student bean = service.findById(id);
		if(bean!=null && bean.getId()>0) {
			bean.setName(name);
			bean.setMathScore(mathScore);
			service.saveOrUpdate(bean);
			
			result.setMessage("Update Success!");
			result.setRcode("0000");
		}else {
			result.setMessage("Update Fail! No Data!");
			result.setRcode("0301");
		}
		return result;
	}
	
	@ApiOperation(value = "刪除學生資料" , notes = "刪除學生資料" )
	@ApiResponses({
		@ApiResponse(responseCode = "200" ,description = "成功"),
		@ApiResponse(responseCode = "404" ,description = "找不到網頁"),
		@ApiResponse(responseCode = "500" ,description = "其他錯誤")
	})
	@DeleteMapping("/delete")
	public ResponseVo deleteStudent(@RequestParam("id") long id) {
		ResponseVo result = new ResponseVo();
		Student bean = service.findById(id);
		if(bean!=null && bean.getId()>0) {
			service.delete(id);
			
			result.setMessage("Delete Success!");
			result.setRcode("0000");
		}else {
			result.setMessage("Delete Fail! No Data!");
			result.setRcode("0301");
		}
		return result;
	}
}

**接著我們啟動專案，網址輸入http://localhost:8080/swagger-ui/**

**可以看到我們剛新增的Rest API呈現在下面**

**點開學生相關操作**

**可以看到剛剛相關的API都有呈現出來**

**我們也可以輸入參數來測試API**

**輸入完後按下Execute**


**可以看到回傳結果**

## open API規範文件

可以輸入以下兩個網址看文件
http://localhost:8080/v2/api-docs

http://localhost:8080/v3/api-docs

###### tags: `Swagger.io`