springboot整合swagger2详细步骤

1.先建一个maven工程，配置pom.xml文件，截图如下：

  4.0.0

  com.mischen.it
  swagger-test
  0.0.1-SNAPSHOT
  jar

  swagger-test
  http://maven.apache.org

  
    UTF-8
  
  
  
		org.springframework.boot
		spring-boot-starter-parent
		1.5.2.RELEASE
		 
	

  
    
        io.springfox
        springfox-swagger2
        2.1.1
    

    
        io.springfox
        springfox-swagger-ui
        2.1.1
    

    
        org.springframework.boot
        spring-boot-starter-web
    

    
        org.springframework.boot
        spring-boot-starter-test
        test
    
    
  
  
		
            spring-milestones
            Spring Milestones
            https://repo.spring.io/milestone
            
                false
            
        
        
            repository.springframework.maven.release
            Spring Framework Maven Release Repository
            http://maven.springframework.org/milestone/
        
        
            org.springframework
             http://maven.springframework.org/snapshot
        
        
            spring-milestone
            Spring Maven MILESTONE Repository
            http://repo.spring.io/libs-milestone
        
        
            spring-release
            Spring Maven RELEASE Repository
            http://repo.spring.io/libs-release
        
	

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 users = Collections.synchronizedMap(new HashMap());
	
	@ApiOperation(value="获取客服", notes="根据cid获取客服")
    @ApiImplicitParam(name = "cid", value = "客户id", required = true, dataType = "String")
	@ResponseBody
	@GetMapping("/getCenter")
	public ApiReturnObject getCenter(String cid) {
		Map map=new LinkedHashMap();
		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 map=new LinkedHashMap();
		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 getCinterCall(@PathVariable String cid) {
		RusultObject ret=new RusultObject();
		Map map=new LinkedHashMap();
		map.put("cid",cid);
		map.put("name","客服");
		ret.setResult(map);
		ret.setStatus("ok");
		return new ResponseEntity(ret, HttpStatus.OK);
	}
	
	/**
	 * 查询用户列表
	 * @return
	 */
	@ApiOperation(value="获取用户列表", notes="获取用户列表")
	@RequestMapping(value = "users", method = RequestMethod.GET)
	public ResponseEntity getUserList (){
		JsonResult r = new JsonResult();
		try {
			//List userList = new ArrayList(users.values());
			Map map=new LinkedHashMap();
			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