Swagger2構建強大的RESTful API文件實戰
阿新 • • 發佈:2018-11-03
一 點睛
RESTful API的重磅好夥伴Swagger2,它可以輕鬆的整合到Spring Boot中,並與Spring MVC程式配合組織出強大RESTful API文件。它既可以減少我們建立文件的工作量,同時說明內容又整合入實現程式碼中,讓維護文件和修改程式碼整合為一體,可以讓我們在修改程式碼邏輯的同時方便的修改文件說明。另外Swagger2也提供了強大的頁面測試功能來除錯每個RESTful API。
二 實戰
1 新增Swagger2依賴
<dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.2.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.2.2</version> </dependency> </dependencies>
2 建立配置類Swagger2
/* 通過@Configuration註解,讓Spring來載入該類配置。再通過@EnableSwagger2註解來啟用Swagger2。 再通過createRestApi函式建立Docket的Bean之後,apiInfo()用來建立該Api的基本資訊(這些基本資訊會展現在文件頁面中)。select()函式返回一個ApiSelectorBuilder例項用來控制哪些介面暴露給Swagger來展現,本例採用指定掃描的包路徑來定義,Swagger會掃描該包下所有Controller定義的API,併產生文件內容(除了被@ApiIgnore指定的請求)。 */ package com.didispace; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.ApiInfo; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 public class Swagger2 { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.didispace.web")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Spring Boot中使用Swagger2構建RESTful APIs") .description("更多Spring Boot相關文章請關注:http://blog.didispace.com/") .termsOfServiceUrl("http://blog.didispace.com/") .contact("程式猿DD") .version("1.0") .build(); } }
3 新增控制器UserController
/* 通過@ApiOperation註解來給API增加說明、通過@ApiImplicitParams、@ApiImplicitParam註解來給引數增加說明。 */ package com.didispace.web; import com.didispace.domain.User; import java.util.*; import io.swagger.annotations.*; import org.springframework.web.bind.annotation.*; @RestController @RequestMapping(value="/users") // 通過這裡配置使下面的對映都在/users下,可去除 public class UserController { static Map<Long, User> users = Collections.synchronizedMap(new HashMap<Long, User>()); @ApiOperation(value="獲取使用者列表", notes="") @RequestMapping(value={""}, method=RequestMethod.GET) public List<User> getUserList() { List<User> r = new ArrayList<User>(users.values()); return r; } @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"; } @ApiOperation(value="獲取使用者詳細資訊", notes="根據url的id來獲取使用者詳細資訊") @ApiImplicitParam(name = "id", value = "使用者ID", required = true, dataType = "Long", paramType = "path") @RequestMapping(value="/{id}", method=RequestMethod.GET) public User getUser(@PathVariable Long id) { return users.get(id); } @ApiOperation(value="更新使用者詳細資訊", notes="根據url的id來指定更新物件,並根據傳過來的user資訊來更新使用者詳細資訊") @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "使用者ID", required = true, dataType = "Long", paramType = "path"), @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"; } @ApiOperation(value="刪除使用者", notes="根據url的id來指定刪除物件") @ApiImplicitParam(name = "id", value = "使用者ID", required = true, dataType = "Long", paramType = "path") @RequestMapping(value="/{id}", method=RequestMethod.DELETE) public String deleteUser(@PathVariable Long id) { users.remove(id); return "success"; } }
4 新增實體類
package com.didispace.domain;
public class User {
private Long id;
private String name;
private Integer age;
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 Integer getAge() {
return age;
}
public void setAge(Integer age) {
this.age = age;
}
}
5 新增啟動類
package com.didispace;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
三 測試
1 瀏覽器輸入http://localhost:8080/swagger-ui.html
2 除錯功能
四 參考