1.先建一个maven工程,配置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>com.mischen.it</groupId>
<artifactId>swagger-test</artifactId>
<version>0.0.1-SNAPSHOT</version>
<packaging>jar</packaging>
<name>swagger-test</name>
<url>http://maven.apache.org</url>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>1.5.2.RELEASE</version>
<relativePath/>
</parent>
<dependencies>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.1.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.1.1</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>
</dependency>
</dependencies>
<repositories>
<repository>
<id>spring-milestones</id>
<name>Spring Milestones</name>
<url>https://repo.spring.io/milestone</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
<repository>
<id>repository.springframework.maven.release</id>
<name>Spring Framework Maven Release Repository</name>
<url>http://maven.springframework.org/milestone/</url>
</repository>
<repository>
<id>org.springframework</id>
<url> http://maven.springframework.org/snapshot</url>
</repository>
<repository>
<id>spring-milestone</id>
<name>Spring Maven MILESTONE Repository</name>
<url>http://repo.spring.io/libs-milestone</url>
</repository>
<repository>
<id>spring-release</id>
<name>Spring Maven RELEASE Repository</name>
<url>http://repo.spring.io/libs-release</url>
</repository>
</repositories>
</project>
2.先建SwaggerTest 启动类:
package com.mischen.it.swagger;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.ComponentScan;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* Hello world!
*
*/
@SpringBootApplication
@EnableSwagger2
public class SwaggerTest
{
public static void main(String[] args) {
SpringApplication.run(SwaggerTest.class, args);
}
}
3.创建Swagger配置类:
package com.mischen.it.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
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() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.mischen.it.controller"))
.paths(PathSelectors.any())
.build();
}
//配置在线文档的基本信息
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("springboot利用swagger构建api文档")
.description("简单优雅的restfun风格,https://me.csdn.net/blog/miachen520")
.termsOfServiceUrl("https://me.csdn.net/blog/miachen520")
.version("1.0")
.build();
}
}
这里可以根据项目的实际情况将上面的参数做相应修改
4.创建/swagger-test/src/main/resources/application.yml:
server:
port: 8763
这里可以设置项目当中使用到的一些配置,这里只是简单的做了一个访问端口的配置,其他配置根据项目需要适当添加
5.创建基础实体类RusultObject和JsonResult,User:
package com.mischen.it.entity;
public class RusultObject {
private String status;
private Object result;
public String getStatus() {
return status;
}
public void setStatus(String status) {
this.status = status;
}
public Object getResult() {
return result;
}
public void setResult(Object result) {
this.result = result;
}
}
package com.mischen.it.entity;
public class JsonResult {
private String status;
private Object result;
public String getStatus() {
return status;
}
public void setStatus(String status) {
this.status = status;
}
public Object getResult() {
return result;
}
public void setResult(Object result) {
this.result = result;
}
}
package com.mischen.it.entity;
import java.util.Date;
public class User {
private int id;
private String username;
private int age;
private Date ctm;
public int getId() {
return id;
}
public void setId(int id) {
this.id = id;
}
public String getUsername() {
return username;
}
public void setUsername(String username) {
this.username = username;
}
public int getAge() {
return age;
}
public void setAge(int age) {
this.age = age;
}
public Date getCtm() {
return ctm;
}
public void setCtm(Date ctm) {
this.ctm = ctm;
}
}
6.创建一个Controller,用于展示api接口:
package com.mischen.it.controller;
import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Controller;
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.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;
import com.mischen.it.entity.ApiReturnObject;
import com.mischen.it.entity.JsonResult;
import com.mischen.it.entity.RusultObject;
import com.mischen.it.entity.User;
import com.mischen.it.util.ApiReturnUtil;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
@Api("客服接口")
@Controller
@RequestMapping("/checkcenter")
public class CheckCenterController {
// 创建线程安全的Map
static Map<Integer, User> users = Collections.synchronizedMap(new HashMap<Integer, User>());
@ApiOperation(value="获取客服", notes="根据cid获取客服")
@ApiImplicitParam(name = "cid", value = "客户id", required = true, dataType = "String")
@ResponseBody
@GetMapping("/getCenter")
public ApiReturnObject getCenter(String cid) {
Map<String,String> map=new LinkedHashMap<String,String>();
map.put("cid",cid);
map.put("name","客服");
return ApiReturnUtil.success(map);
}
@ApiOperation(value="获取客服", notes="根据cid获取客服")
@ApiImplicitParam(name = "cid", value = "客户id", required = true, dataType = "String")
@ResponseBody
@PostMapping("/getCenter/{cid}")
public ApiReturnObject getCenter2(@PathVariable String cid) {
Map<String,String> map=new LinkedHashMap<String,String>();
map.put("cid",cid);
map.put("name","客服");
return ApiReturnUtil.success(map);
}
@ApiOperation(value="测试接口api", notes="根据cid获取客服信息,this is test api")
@ApiImplicitParam(name = "cid", value = "客户id", required = true, dataType = "String")
@ResponseBody
@PostMapping("/getCenter/{cid}")
public ResponseEntity<RusultObject> getCinterCall(@PathVariable String cid) {
RusultObject ret=new RusultObject();
Map<String,String> map=new LinkedHashMap<String,String>();
map.put("cid",cid);
map.put("name","客服");
ret.setResult(map);
ret.setStatus("ok");
return new ResponseEntity<RusultObject>(ret, HttpStatus.OK);
}
/**
* 查询用户列表
* @return
*/
@ApiOperation(value="获取用户列表", notes="获取用户列表")
@RequestMapping(value = "users", method = RequestMethod.GET)
public ResponseEntity<JsonResult> getUserList (){
JsonResult r = new JsonResult();
try {
//List<User> userList = new ArrayList<User>(users.values());
Map<String,String> map=new LinkedHashMap<String,String>();
map.put("aa", "小红");
map.put("bb", "小明");
r.setResult(map);
r.setStatus("ok");
} catch (Exception e) {
r.setResult(e.getClass().getName() + ":" + e.getMessage());
r.setStatus("error");
e.printStackTrace();
}
return ResponseEntity.ok(r);
}
}
注意,上面的controller方法只是一个示例,里面的具体方法还需要手动再修改一下,具体实现细节还需要简单的调试一下,
可以根据项目需要进行适当修改,以便可用
7.启动springboot工程,访问http://localhost:8763/swagger-ui.html#/,截图如下所示:
至此,springboot与swagger2整合完成,大家可以写controller来展示各种api接口了,上面的保存还需要在controller上做简单的修改
源码下载链接地址:https://github.com/markchen520/spring-boot/tree/master/swagger-test