Swagger是一个开源框架,可以在将你的Restful API文档化,供其他访问者浏览,包括应该提交的JSON格式,获得响应JSON格式等。
首先在Spring Boot的pom.xml中引入swagger2包支持:
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> <scope>compile</scope> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.6.1</version> <scope>compile</scope> </dependency>
|
springfox是产生API文档,而swagger-ui 则是RestAPI的界面。创建一个RestController ,定义API:
@RestController @Api(value="/customer",description="Customer Profile",produces ="application/json") @RequestMapping("/customer") public class CustomerController { @ApiOperation(value="get customer",response=Customer.class) @ApiResponses(value={ @ApiResponse(code=200,message="Customer Details Retrieved",response=Customer.class), @ApiResponse(code=500,message="Internal Server Error"), @ApiResponse(code=404,message="Customer not found") }) @RequestMapping(value="/getCustomer",method=RequestMethod.GET,produces="application/json") public ResponseEntity<Customer> getCustomer(){ Customer cust = new Customer(); cust.setName("Sagar"); cust.setId(1234); cust.setAddress("Pune"); return new ResponseEntity<Customer>(cust, HttpStatus.OK); } }
|
这里特殊的地方就是多了很多新的注释:
1. @Api 定义这个控制器是什么
2. @ApiOperation 定义请求方法
3. @ApiResponses 定义方法可能返回的所有响应。下面需要激活Swagger的配置:
@Configuration @EnableSwagger2 public class SwaggerConfig{ @Bean public Docket produceApi(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.hotel.main.controllers")) .paths(paths()) .build(); } // Describe your apis private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Hotel Management Rest APIs") .description("This page lists all the rest apis for Hotel Management App.") .version("1.0-SNAPSHOT") .build(); } // Only select apis that matches the given Predicates. private Predicate<String> paths() { // Match all paths except /error return Predicates.and( PathSelectors.regex("/customer.*"), Predicates.not(PathSelectors.regex("/error.*")) ; } }
|
@EnableSwagger2 是在应用启动时激活swagger ;Docket - 它是一个构建器,在swagger-springmvc框架中充当主要接口。它的构建字段如下:
apiInfo - 它返回一个ApiInfoBuilder,它指定Rest API的标题,描述等。
select()- 它返回ApiSelectorBuilder的一个实例 ,它提供了一种控制Swagger公开的端点的方法。
apis - 提供RequestHandlerSelectors,它指定basepackage来扫描所有控制器。
paths() - 提供API的映射端点。
最后是启动类:
@SpringBootApplication @EnableSwagger2 public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } }
|
Swagger生成与Spring Boot - DZone集成