SpringBoot之Swagger2文檔生成

SpringBoot之Swagger2文檔生成

一、Swagger2介紹

編寫和維護接口文檔是每一個程序員的職責，前面咱們已經寫好的接口如今須要提供一份文檔，這樣才能方便調用者使用。考慮到編寫接口文檔是一個很是枯燥的工做，咱們採用Swagger2這套自動化文檔工具來生成文檔，它能夠輕鬆的整合到Spring Boot中，並與Spring MVC程序配合組織出強大RESTful API文檔。 

二、SpringBoot開啓Swagger2支持

第一步：在pom.xml中加入Swagger2的依賴

<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.7.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.7.0</version> </dependency>

 

第二步：建立Swagger2配置類

package com.offcn.config;   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 SwaggerConfig {     public Docket createRestApi() {         return new Docket(DocumentationType.SWAGGER_2)                 .apiInfo(apiInfo())                 .select()                 .apis(RequestHandlerSelectors.basePackage("com.offcn.controller"))                 .paths(PathSelectors.any())                 .build();     }     private ApiInfo apiInfo() {         return new ApiInfoBuilder()                 .title("Spring Boot中使用Swagger2構建RESTful APIs")                 .description("優就業")                 .termsOfServiceUrl("http://www.ujiuye.com/")                 .contact("Sunny")                 .version("1.0")                 .build();     } }

 

三、修改Controller增長文檔註釋

經過@ApiOperation註解來給API增長說明 經過@ApiImplicitParams@ApiImplicitParam註解來給參數增長說明

/**  * 更新指定id用戶信息  * @param id  * @param user  * @return  */ @PutMapping("/{id}") @ApiOperation(value="更新指定id用戶信息", notes="根據id更新用戶信息") @ApiImplicitParams({          @ApiImplicitParam(name = "id", value = "用戶ID", required = true, dataType = "Long"),          @ApiImplicitParam(name = "user", value = "用戶詳細實體user", required = true, dataType = "User")      }) public String updateUser(@PathVariable("id") Long id,User user) { user.setId(id); userRepository.saveAndFlush(user); return "success"; }   /***  * 刪除指定id用戶  * @param id  * @return  */ @DeleteMapping("/{id}") @ApiOperation(value="刪除指定id用戶信息", notes="根據id刪除用戶信息")     @ApiImplicitParam(name = "id", value = "用戶id", required = true, dataType = "Long") public String deleteUser(@PathVariable("id") Long id) {   userRepository.deleteById(id); return "success";   }

 

四、查看Swagger2文檔

重啓應用訪問地址：http://localhost:8080/swagger-ui.html 

點開每一個接口，能夠查看接口詳情