Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务,本文使用的swagger_ui.html,使用可视化页面来描述文件,接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求,这里写了一个简单的demo进行学习。
1.新建一个Springboot项目Springboot-swagger
2.导入依赖
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33
| <dependencies>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency>
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency>
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> <exclusions> <exclusion> <groupId>org.junit.vintage</groupId> <artifactId>junit-vintage-engine</artifactId> </exclusion> </exclusions> </dependency> </dependencies>
|
3.新建SwaggerConfig类
1 2 3 4
| @Configuration @EnableSwagger2 public class SwaggerConfig { }
|
4.启动SwaggerApplication服务,页面访问http://localhost:8080/swagger-ui.html
5.配置Swagger
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
| @Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket docket(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()); } private ApiInfo apiInfo(){ Contact contact = new Contact("ZL","http://www.zllwsy.com","zllwsy@outlook.com"); return new ApiInfo( "ZL的SwaggerAPI文档", "学习永无止境", "v1.0", "urn:tos", contact, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList() ); } }
|
6.配置Swagger分组
7.配置多个分组,多个Docket实例
1 2 3 4 5 6 7 8 9 10 11 12
| @Bean public Docket docket1(){ return new Docket(DocumentationType.SWAGGER_2).groupName("A"); } @Bean public Docket docket2(){ return new Docket(DocumentationType.SWAGGER_2).groupName("B"); } @Bean public Docket docket3(){ return new Docket(DocumentationType.SWAGGER_2).groupName("C"); }
|
8.Swagger的注解注释
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
| //实体类 @ApiModel("用户实体类") public class User { @ApiModelProperty("用户名") public String username; @ApiModelProperty("密码") public String password; }
//控制类 @RestController public class HelloController { @GetMapping(value = "/hello") public String hello(){ return "hello"; } //只要我们的接口中,返回值存在实体类,就会被扫描到Swagger中 @PostMapping(value = "/user") public User user(){ return new User(); } //@ApiOperation放在方法上 @ApiOperation("Hello控制类") @GetMapping(value = "/hello2") public String hello2(@ApiParam("用户名") String username){ return "hello"+username; } } @ApiModel @ApiModelProperty @ApiOperation @ApiParam
|
9.关于Swagger的更多配置
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56
| @Configuration @EnableSwagger2 public class SwaggerConfig {
@Bean public Docket docket1(){ return new Docket(DocumentationType.SWAGGER_2).groupName("A"); } @Bean public Docket docket2(){ return new Docket(DocumentationType.SWAGGER_2).groupName("B"); } @Bean public Docket docket3(){ return new Docket(DocumentationType.SWAGGER_2).groupName("C"); } @Bean public Docket docket(Environment environment){ Profiles profiles=Profiles.of("dev","test"); boolean flag = environment.acceptsProfiles(profiles); return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .groupName("ZL") .enable(flag) .select() .apis(RequestHandlerSelectors.basePackage("cn.zl.swagger.controller")) .build(); } private ApiInfo apiInfo(){ Contact contact = new Contact("ZL","http://www.zllwsy.com","zllwsy@outlook.com"); return new ApiInfo( "ZL的SwaggerAPI文档", "学习永无止境", "v1.0", "urn:tos", contact, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList() ); } }
|
10.重新启动SwaggerApplication服务,访问http://localhost:8081/swagger-ui.html