1.在pom.xml中添加添加Swagger2依赖
<!--swagger2 依赖开始--> <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 依赖结束-->
2.在服务启动类的同级创建Swagger2配置类SwaggerConfig
package com.study.model; 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 { @Bean public Docket createRestApi() { ApiInfo apiInfo = new ApiInfoBuilder() .title("使用Swagger2构建RESTful APIs") .description("客户端与服务端接口文档") .termsOfServiceUrl("http://localost:8080") .contact("test swagger") .version("1.0.0") .build(); return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo) .select() .apis(RequestHandlerSelectors.basePackage("com.study.model")) .paths(PathSelectors.any()) .build(); } } 注意: 上面的包名是对应工程的包 我的包是这样的
上述代码中,通过@Configuration注解,让Spring来加载该类配置,通过@EnableSwagger2注解来启用Swagger2。
再通过createRestApi函数创建Docket的Bean之后,apiInfo是用来创建接口文档的基本信息(这些基本信息会展现在文档页面中)。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现,本例采用指定扫描的包路径来定义,Swagger会扫描该包下所有Controller定义的API,并产生文档内容(除了被@ApiIgnore指定的请求)。
3.给对应API接口创建描述信息
package com.study.model.controler; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiImplicitParams; import io.swagger.annotations.ApiOperation; import org.springframework.web.bind.annotation.*; @RestController @RequestMapping(value="/user") public class UserController { @ApiOperation(value="获取用户信息", notes="欢迎用户") @RequestMapping(method = RequestMethod.GET) public String user(){ return "hello world!"; } @ApiOperation(value="获取用户信息", notes="根据{username}获取对应用户信息") @RequestMapping(value="/get/{username}",method = RequestMethod.GET) public String get(@PathVariable("username") String username){ return "welcome," + username; } @ApiOperation(value="登录", notes="根据URL中的username、pwd进行用户登录验证") @ApiImplicitParams({ @ApiImplicitParam(name = "username", value = "用户名", required = true,paramType = "query", dataType = "string"), @ApiImplicitParam(name = "pwd", value = "密码", required = true,paramType = "query", dataType = "string") }) @RequestMapping(value="/login",method = RequestMethod.GET) public String login(@RequestParam String username, @RequestParam String pwd){ return "user:" + username + ",password:" + pwd; } }
4.运行后,访问 http://localhost:8080/swagger-ui.html 就能 看到之前所展示的RESTFUI API的页面