創建module

(1) 請參考Day27 module
(2) 使用JSON相關設置請參考Day29

一、RESTful

(1) 何謂RESTful

RESTful(Representational State Transfer)指的是一種軟體架構風格，透過HTTP的請求方法與狀態碼進行交互溝通

(2) RESTful特點

透過請求方式對應操作

回應狀態碼

REST Style URL

二、RESTful實戰

(1) 創建範例

創建DemoController

@RestController
@RequestMapping("api/emp")
public class DemoController {

    @PostMapping
    public String createEmp(@RequestBody Employee emp){
        System.out.println(emp.toString());
        return "createEmp success";
    }


    @GetMapping(path = "/{empId}")
    public String readEmp( @PathVariable("empId") String empId){
        System.out.println("query empId: " + empId);
        return "readEmp success";
    }

    @PutMapping
    public String updateEmp(){
        return "updateEmp success";
    }

    @DeleteMapping(path = "/{empId}")
    public String deleteEmp(@PathVariable("empId") String empId){
        System.out.println("delete empId: " + empId);
        return "deleteEmp success";
    }
}

創建Employee

public class Employee {

    private String empId;
    private String name;
    private String email;
    private int age;
    private String gender;
    private LocalDate entryDate;
    //getter and setter略
}

(2) Demo

Create

Read

Update

Delete

三、Swagger

在現今前後端分離架構會透過Swagger產生API文件來降低前後端溝通的成本也能透過API文件頁面執行API的操作。原先最常使用的SpringFox已不再維護，這個部份我們將使用Springdoc-openapi來進行演示。

(1) 配置

maven

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.6.0</version>
</dependency>

springmvc-servlet.xml，在原有的Converter中加入ByteArrayHttpMessageConverter

<mvc:message-converters>
    <bean class="org.springframework.http.converter.ByteArrayHttpMessageConverter"/>
    <bean class="org.springframework.http.converter.json.MappingJackson2HttpMessageConverter">
        <property name="objectMapper" ref="objectMapper"/>
    </bean>
</mvc:message-converters>

創建OpenApiConfig

@Configuration
@EnableWebMvc
@ComponentScan(basePackages = {"org.springdoc"})
public class OpenApiConfig implements WebMvcConfigurer {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Day34 Demo API")
                        .version("1.0")
                        .description("API Documentation"));
    }
}

(2) 常用Annotation

(3) 範例建置

@Tag(name = "DemoController" ,description = "Employee的CRUD")
@RestController
@RequestMapping("api/emp")
public class DemoController {
  @Operation(summary = "Gets employee by empId",
            description= "employee must exist")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "400", description = "Invalid ID supplied"),
            @ApiResponse(responseCode = "404", description = "Customer not found")})
    @GetMapping(path = "/{empId}")
    public String readEmp( @PathVariable("empId") String empId){
        System.out.println("query empId: " + empId);
        return "readEmp success";
    }
  //其他略
}

Demo

Reference

• Java Web Services Tutorial - javatpoint
• REST API response codes - arubanetworks
• REST API: JAX-RS vs Spring - Baeldung
• SOAP vs REST：如何選擇？ - ExplainThis
• springdoc-openapi - doc
• Malformed (base64 encoded) api-docs JSON when MappingJackson2HttpMessageConverter is active - springdoc issue#2143
• Usage in Spring MVC Application (Not Spring Boot) - springdoc issue#2343