springboot 學習筆記【5】使用Swagger2構建RESTful APIs

接上一篇springboot 學習筆記【4】Spring Boot構建RESTful API

---

上一篇博客中寫了一個簡單的Restful接口的服務，在實際開發中咱們的RESTful API就有可能要面對多個開發人員或多個開發團隊：IOS開發、Android開發或是Web開發等。爲了減小與其餘團隊平時開發期間的頻繁溝通成本，傳統作法咱們會建立一份RESTful API文檔來記錄全部接口細節，然而這樣的作法有如下幾個問題：

• 因爲接口衆多，而且細節複雜（須要考慮不一樣的HTTP請求類型、HTTP頭部信息、HTTP請求內容等），高質量地創- - 建這份文檔自己就是件很是吃力的事，下游的抱怨聲不絕於耳。
• 隨着時間推移，不斷修改接口實現的時候都必須同步修改接口文檔，而文檔與代碼又處於兩個不一樣的媒介，除非有嚴格的管理機制，否則很容易致使不一致現象。 爲了解決上面兩個問題，有一個開源工具能夠幫助咱們快速構建Restful接口文檔。swagger 下面咱們將上一篇博客的源代碼添加Swagger。 ###添加swagger依賴

<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>

###建立Swagger2配置類 在main函數同級目錄建立swagger2類。

@Configuration
@EnableSwagger2
public class swagger2 {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                 //Restful接口的basepackage
                .apis(RequestHandlerSelectors.basePackage("pub.zhouhui.controller")) 
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2構建RESTful APIs")
                .version("1.0")
                .build();
    }
}

如上代碼所示，經過@Configuration註解，讓Spring來加載該類配置。再經過@EnableSwagger2註解來啓用Swagger2。 再經過createRestApi函數建立Docket的Bean以後，apiInfo()用來建立該Api的基本信息（這些基本信息會展示在文檔頁面中）。select()函數返回一個ApiSelectorBuilder實例用來控制哪些接口暴露給Swagger來展示，本例採用指定掃描的包路徑來定義，Swagger會掃描該包下全部Controller定義的API，併產生文檔內容（除了被@ApiIgnore指定的請求）。 ###添加文檔內容 在完成了上述配置後，其實已經能夠生產文檔內容，可是這樣的文檔主要針對請求自己，而描述主要來源於函數等命名產生，對用戶並不友好，咱們一般須要本身增長一些說明來豐富文檔內容。以下所示，咱們經過@ApiOperation註解來給API增長說明、經過@ApiImplicitParams、@ApiImplicitParam註解來給參數增長說明。

@RestController
@RequestMapping(value="/user")
public class UserController {
    @Autowired
    private UserRepository userRepository;
    @ApiOperation(value="獲取用戶列表", notes="")
    @RequestMapping(value="/findall",method= RequestMethod.GET)
    public List<User> findall(){
        List<User> alluser = userRepository.findAll();
        return alluser;
    }
    @ApiOperation(value="經過ID查找用戶", notes="")
    @ApiImplicitParam(name = "id", value = "用戶id", required = true, dataType = "Long")
    @RequestMapping(value="/{id}", method=RequestMethod.GET)
    public User getUser(@PathVariable String id) {
        // 處理"/users/{id}"的GET請求，用來獲取url中id值的User信息
        // url中的id可經過@PathVariable綁定到函數的參數中
        return userRepository.findByName(id);
    }
    @ApiOperation(value="建立用戶", notes="根據User對象建立用戶")
    @ApiImplicitParam(name = "user", value = "用戶詳細實體user", required = true, dataType = "User")
    @RequestMapping(value="/add", method=RequestMethod.POST)
    public String addUser(@RequestBody User user){
        User users = new User();
        users.setId(user.getId());
        users.setName(user.getName());
        users.setAge(user.getAge());
        userRepository.save(users);
        return "success";
    }
    @ApiOperation(value="更新用戶詳細信息", notes="根據url的id來指定更新對象，並根據傳過來的user信息來更新用戶詳細信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用戶ID", required = true, dataType = "Long"),
            @ApiImplicitParam(name = "user", value = "用戶詳細實體user", required = true, dataType = "User")
    })
    @RequestMapping(value="/update/{id}", method=RequestMethod.POST)
    public String updateUser(@PathVariable long id,  @RequestBody User user){
        User users = new User();
        users.setId(id);
        users.setName(user.getName());
        users.setAge(user.getAge());
        userRepository.save(users);
        return "success";
    }
    @ApiOperation(value="刪除用戶", notes="根據url的id來指定刪除對象")
    @ApiImplicitParam(name = "id", value = "用戶ID", required = true, dataType = "Long")
    @RequestMapping(value="/{id}", method=RequestMethod.DELETE)
    public String deldeteUser(@PathVariable long id) {
        // 處理"/users/{id}"的GET請求，用來獲取url中id值的User信息
        // url中的id可經過@PathVariable綁定到函數的參數中
        userRepository.delete(id);
        return "success";
    }
}

完成上述代碼添加上，啓動Spring Boot程序，訪問：http://localhost:8080/swagger-ui.html 就能看到前文所展現的RESTful API的頁面。

咱們能夠再點開具體的API請求，以GET類型的/users/findall請求爲例,點擊 Try it out結果以下

完整工程