16、springcloud整合Swagger2构建Restful服务的APIs
公众号： java乐园Spring Cloud将服务注册到了Eureka上，可以从Eureka的UI界面中，看到有哪些服务已经注册到了Eureka Server上；但是如果想查看当前服务提供了哪些RESTful接口方法的话，就无法从Eureka Server获取了，而传统的方法是梳理一个接口文档来供开发人员之间来进行交流。这种情况下经常会造成文档和代码的不一致性，比如说代码改了，但是接口文档还没.
·
公众号： java乐园
Spring Cloud将服务注册到了Eureka上，可以从Eureka的UI界面中，看到有哪些服务已经注册到了Eureka Server上；但是如果想查看当前服务提供了哪些RESTful接口方法的话，就无法从Eureka Server获取了，而传统的方法是梳理一个接口文档来供开发人员之间来进行交流。这种情况下经常会造成文档和代码的不一致性，比如说代码改了，但是接口文档还没来得及修改等问题，而Swagger2则给我们提供了一套完美的解决方案，下面来看看Swagger2是如何来解决这个问题的。
1、 新建项目sc-swagger2，对应的pom.xml文件
<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>spring-cloud</groupId>
<artifactId>sc-swagger2</artifactId>
<version>0.0.1-SNAPSHOT</version>
<packaging>jar</packaging>
<name>sc-swagger2</name>
<url>http://maven.apache.org</url>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.0.4.RELEASE</version>
</parent>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-dependencies</artifactId>
<version>Finchley.RELEASE</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<maven.compiler.source>1.8</maven.compiler.source>
<maven.compiler.target>1.8</maven.compiler.target>
</properties>
<dependencies>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
</dependencies>
</project>
2、 新建springboot启动类
package sc.swagger2;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class Swagger2Application {
public static void main(String[] args) {
SpringApplication.run(Swagger2Application.class, args);
}
}
3、 新建Swagger2配置类
package sc.swagger2.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
@EnableSwagger2
public class Swagger2Config {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("sc.swagger2"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建RESTful APIs")
.description("更多Spring Boot相关文章请关注: JAVA乐园 公众号")
.termsOfServiceUrl("https://edu.csdn.net/lecturer/995")
.contact(new Contact("huangjinjin", //
"https://edu.csdn.net/lecturer/995",//
"happyhuangjinjin@sina.com"))
.version("1.0")
.build();
}
}
4、 新建一个模拟的Controller
package sc.swagger2.controller;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
import sc.swagger2.model.User;
@Api(value="用户管理")
@Controller
public class UserController {
@ApiResponses({ @ApiResponse(code = 000000, message = "操作成功"),
@ApiResponse(code = 000001, message = "服务器内部异常") })
@GetMapping(value = "/feign/user/getUser/{id}")
@ResponseBody
@ApiOperation(value = "获取根据Id用户信息",response = User.class)
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long",example="100")
public Map<String, Object> getUser(@PathVariable Long id) {
Map<String, Object> result = new HashMap<String, Object>();
result.put("code", "000000");
result.put("msg", "success");
User u = new User();
u.setId(1L);
u.setAge(23);
u.setUserName("huangjinjin");
u.setPosition("cto");
result.put("body", u);
return result;
}
@ApiResponses({ @ApiResponse(code = 000000, message = "操作成功"),
@ApiResponse(code = 000001, message = "服务器内部异常") })
@RequestMapping(value = "/feign/user/listUser", method = RequestMethod.GET)
@ResponseBody
@ApiOperation(value = "获取用户列表")
public Map<String, Object> listUser() {
Map<String, Object> result = new HashMap<String, Object>();
result.put("code", "000000");
result.put("msg", "success");
User u = new User();
u.setId(1L);
u.setAge(23);
u.setUserName("huangjinjin");
u.setPosition("cto");
List<User> list = new ArrayList<User>();
list.add(u);
result.put("body", list);
return result;
}
@ApiResponses({ @ApiResponse(code = 000000, message = "操作成功"),
@ApiResponse(code = 000001, message = "服务器内部异常") })
@PostMapping(value = "/feign/user/addUser")
@ResponseBody
@ApiOperation(value = "添加用户", notes = "根据User对象创建用户")
@ApiImplicitParams({ @ApiImplicitParam(name = "userName", value = "用户名", required = true, dataType = "String"),
@ApiImplicitParam(name = "age", value = "年龄", required = true, dataType = "String"),
@ApiImplicitParam(name = "position", value = "职位", required = true, dataType = "String"),
@ApiImplicitParam(name = "id", value = "用户ID", required = false, dataType = "Long",example="100")})
public Map<String, Object> addUser(User user) {
Map<String, Object> result = new HashMap<String, Object>();
result.put("code", "000000");
result.put("msg", "success");
result.put("body", 1);
return result;
}
@ApiResponses({ @ApiResponse(code = 000000, message = "操作成功"),
@ApiResponse(code = 000001, message = "服务器内部异常") })
@ApiOperation(value = "更新用户")
@PutMapping(value = "/feign/user/updateUser")
@ResponseBody
@ApiImplicitParams({ @ApiImplicitParam(name = "userName", value = "用户名", required = true, dataType = "String"),
@ApiImplicitParam(name = "age", value = "年龄", required = true, dataType = "String"),
@ApiImplicitParam(name = "position", value = "职位", required = true, dataType = "String"),
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", example="100")})
public Map<String, Object> updateUser(User user) {
Map<String, Object> result = new HashMap<String, Object>();
result.put("code", "000000");
result.put("msg", "success");
result.put("body", 1);
return result;
}
@ApiResponses({ @ApiResponse(code = 000000, message = "操作成功"),
@ApiResponse(code = 000001, message = "服务器内部异常") })
@DeleteMapping(value = "/feign/user/deleteUser/{id}")
@ResponseBody
@ApiOperation(value = "删除用户")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long",example="100")
public Map<String, Object> deleteUser(@PathVariable Long id) {
Map<String, Object> result = new HashMap<String, Object>();
result.put("code", "000000");
result.put("msg", "success");
result.put("body", 1);
return result;
}
}
5、 新建User模型类
package sc.swagger2.model;
import java.io.Serializable;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
@ApiModel
public class User implements Serializable {
private static final long serialVersionUID = 4639927446947303736L;
@ApiModelProperty(name="id", dataType="Long", value="主键ID")
private Long id;
@ApiModelProperty(name="userName", dataType="String", value="姓名", required=true)
private String userName;
@ApiModelProperty(name="age", dataType="String", value="年龄", required=true)
private Integer age;
@ApiModelProperty(name="position", dataType="String", value="职位")
private String position;
public String getUserName() {
return userName;
}
public void setUserName(String userName) {
this.userName = userName;
}
public Integer getAge() {
return age;
}
public void setAge(Integer age) {
this.age = age;
}
public String getPosition() {
return position;
}
public void setPosition(String position) {
this.position = position;
}
public Long getId() {
return id;
}
public void setId(Long id) {
this.id = id;
}
}
6、 启动sc-swagger2项目，并验证是否启动成功
方式一：查看日志
方式二：访问地址
http://127.0.0.1:9092/swagger-ui.html
或者访问http://localhost:9092/v2/api-docs
7、 在界面http://127.0.0.1:9092/swagger-ui.html点击【user-controller】可以看到所有的接口，同时也可以在界面上进行接口调用调试
权威｜前沿｜技术｜干货｜国内首个API全生命周期开发者社区
更多推荐
0
0- 0
已为社区贡献8条内容
所有评论(0)