本文主要講解springboot是如何經過整合Swagger-UI來實現一份至關完善的在線API文檔的。html
Swagger-UI是HTML, Javascript, CSS的一個集合,能夠動態地根據註解生成在線API文檔。java
在pom.xml文件中加入Swagger-UI相關依賴git
<!-- Swagger UI --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency>
添加Swagger配置類Swagger2Configweb
package com.mzm.springboot.config; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import org.springframework.beans.factory.annotation.Value; 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.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 public class Swagger2Config { @Value("${swagger.title}") private String title; public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.mzm.springboot.controller")) //爲當前包下controller生成API文檔 .apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) //爲有@Api註解的Controller生成API文檔 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //爲有@ApiOperation註解的方法生成API文檔 .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder(). title("測試Swagger2") .description("Spring Boot中使用Swagger2構建RESTful APIs") .version("1.0.0") .contact(new Contact("mzm", "https://gitee.com/moses_mao", "297531644@qq.com")) .build(); } }
Swagger對生成API文檔的範圍有三種不一樣的選擇spring
package com.mzm.springboot.controller; import com.mzm.springboot.controller.common.BaseController; import com.mzm.springboot.exception.BusinessException; import com.mzm.springboot.exception.EmBusinessError; import com.mzm.springboot.response.CommonReturnType; import com.mzm.springboot.service.UserSevice; import com.mzm.springboot.service.model.UserModel; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestMethod; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; @Api(tags = "HomeController", description = "後臺首頁管理") @RestController("user") @RequestMapping("/user") public class HomeController extends BaseController { @Autowired private UserSevice userSevice; @ApiOperation("hello word") @RequestMapping(value = "/hello", method = RequestMethod.GET) public String hello() { return "hello world"; } @ApiOperation("獲取單個用戶") @RequestMapping(value = "/get", method = RequestMethod.GET) public CommonReturnType getUser(@RequestParam(name = "id") Integer id) throws BusinessException { UserModel userModel = userSevice.getUserById(id); if (userModel == null) { throw new BusinessException(EmBusinessError.USER_NOT_EXISTS); } return CommonReturnType.create(userModel); } }