Spring boot集成swagger构建接口管理文档
一,swagger简介
swagger是一个工具,用于自动生成web网站对外提供的服务接口文档,并且以web页面的形式进行展示。
优势:可以自动生成API文档 ,能降低前后端的沟通成本。
二,项目的基本结构
三,idea项目构建思路
3.1pom依赖
<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>com.yfy</groupId> <artifactId>bootsw</artifactId> <version>0.0.1-SNAPSHOT</version> <packaging>jar</packaging> <name>bootsw</name> <description>Demo project for Spring Boot</description> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.0.5.RELEASE</version> <relativePath/> <!-- lookup parent from repository --> </parent> <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding> <java.version>1.8</java.version> </properties> <dependencies> <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> </dependency> <!--swagge依赖--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.6.1</version> </dependency> <!--lombok插件依赖--> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <version>1.16.10</version> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> </plugin> </plugins> </build> </project>
3.2application.properties配置
3.3实体类
package com.yfy.bootsw.entity; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; @ApiModel(value = "用户模型") public class UserEntity { @ApiModelProperty(value="id" ,required= true,example = "123") private Integer id; @ApiModelProperty(value="用户姓名" ,required=true,example = "yyyy") private String name; public Integer getId() { return id; } public void setId(Integer id) { this.id = id; } public String getName() { return name; } public void setName(String name) { this.name = name; } @Override public String toString() { return "DemoDoctor [id=" + id + ", name=" + name + "]"; } }
3.4Controller类
package com.yfy.bootsw; import com.yfy.bootsw.entity.UserEntity; import io.swagger.annotations.*; import org.springframework.web.bind.annotation.*; @Api(value = "会员接口") @RestController public class AnimalController { @ApiOperation(value = "接口测试demo", nickname = "swagger接口测试demo昵称") @GetMapping("/getDemo") public String getDemo(){ return "调用方法成功。。。。。"; } @ApiOperation(value = "获取会员信息接口", nickname = "根据userName获取用户相关信息") @ApiImplicitParam(name = "userName", value = "用户名称", required = true, dataType = "String") @PostMapping("/postMember") public String postMember(@RequestParam String userName) { return userName; } @ApiOperation(value = "添加用户信息", nickname = "nickname是什么", notes = "notes是什么", produces = "application/json") @PostMapping("/postUser") @ResponseBody @ApiImplicitParam(paramType = "query", name = "userId", value = "用户id", required = true, dataType = "int") public UserEntity postUser(@RequestBody UserEntity user, @RequestParam("userId") int userId) { if (user.getId() == userId) { return user; } return new UserEntity(); } @ApiOperation(value = "添加用户信息", nickname = "添加用户接口", notes = "测试添加用户的接口", produces = "application/json") @PostMapping("/addUser") @ResponseBody @ApiImplicitParams({@ApiImplicitParam(paramType = "query", name = "userName", value = "用户姓名", required = true, dataType = "String"), @ApiImplicitParam(paramType = "query", name = "id", value = "用户id", required = true, dataType = "int") }) public UserEntity addUser(String userName, int id) { UserEntity userEntity = new UserEntity(); userEntity.setName(userName); userEntity.setId(id); return userEntity; } }
3.5config类的编写
package com.yfy.bootsw.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.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration //spring boot配置注解 @EnableSwagger2 //启用swagger2功能注解 public class Swagger2Config { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select() // api扫包范围 .apis(RequestHandlerSelectors.basePackage("com.yfy.bootsw")).paths(PathSelectors.any()).build(); } /** * 创建该API的基本信息(这些基本信息会展现在文档页面中) * 访问地址:http://项目实际地址/swagger-ui.html * */ private ApiInfo apiInfo() { return new ApiInfoBuilder().title("Swagger接口发布测试").description("测试|Swagger接口功能") //服务条 .termsOfServiceUrl("www.baidu.com") .contact(new Contact("yangjie", "https://blog.csdn.net/OnlyOneFrist", "")) .version("1.0") .build(); } }