java spring swagger

API工具框架Swagger 快速入門

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

2 10439

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();
    }

}