SpringBoot整合Swagger2

一、依赖

<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>

二、Swagger配置类

package com.example.demo.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;

/**
 * @author wyw
 * @Description TODO
 * 接口文档处理类
 * @date 2019/4/2 15:32
 */

@Configuration //用@Configuration注解该类,等价于xml中配置beans;用@Bean标注方法等价于XML中配置bean
public class Swagger2 {

    /**
     *
     * 功能描述: 
     * 创建API应用
     * appinfo()增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例，用来控制哪些接口暴露给Swagger来展示
     * 指定扫描包路径来定义指定要建立API的目录
     * @param: 
     * @return: 
     * @auther: wyw
     * @date: 2019/4/2 16:07
     */
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("Swagger使用demo") //设置栏目名
                .apiInfo(apiInfo())
                .select()  //初始化并返回一个API选择构造器
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())  //设置路径筛选
                .build();  //构建
    }

    /**
     *
     * 功能描述: 
     * 创建API的基本信息（这些信息会展示在文东页面中）
     * 访问地址： http://项目实际地址/swagger-ui.html  例如：http://localhost:8080/swagger-ui.html
     * @param: 
     * @return: 
     * @auther: wyw
     * @date: 2019/4/2 16:10
     */
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档")
                .contact(new Contact("wyw","http://ssish.com","wanyiwen@ssish.com"))
                .description("简单优雅的restful风格")
                //服务条款网址
                //.termsOfServiceUrl("http://blog.csdn.net/forezp")
                .version("1.0")
                .build();

    }

}

用@Configuration注解该类，等价于XML中配置beans；用@Bean标注方法等价于XML中配置bean。

Application.class 加上注解@EnableSwagger2 表示开启Swagger

@SpringBootApplication
@EnableSwagger2 //开启Swagger
public class DemoApplication {

   public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }

}

三、Restful 接口

package com.example.demo.controller;

import com.example.demo.bean.JsonResult;
import com.example.demo.constant.ConstantStatus;
import com.example.demo.entity.User;
import com.example.demo.repository.UserRepository;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.servlet.ModelAndView;
import springfox.documentation.annotations.ApiIgnore;

import java.util.*;

/**
 * @author 万义文
 * @Description TODO
 * @date 2018/12/22 13:10
 */
@RestController
@RequestMapping("/users")
@Api(value = "UserController服务端接口文档", tags = "UserController服务端接口文档说明,包含用户的增删改查")//用在类上，说明该类的作用 访问swagger地址http://localhost:8081/swagger-ui.html
public class UserController {

    /*@Api：用在类上，说明该类的作用。

    @ApiOperation：注解来给API增加方法说明。

    @ApiImplicitParams : 用在方法上包含一组参数说明。

    @ApiImplicitParam：用来注解来给方法入参增加说明。

    @ApiResponses：用于表示一组响应

    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

    *  code：数字，例如400

    *  message：信息，例如"请求参数没填好"

            *  response：抛出异常的类

    @ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）

            *  @ApiModelProperty：描述一个model的属性*/

    //创建线程安全的Map
    static Map<Integer,User> users = Collections.synchronizedMap(new HashMap<Integer, User>());


    @ApiOperation(value = "获取用户详细信息",notes = "根据url的id来获取用户详细信息")
    @ApiImplicitParams(@ApiImplicitParam(name = "id",value = "用户id",required = true,dataType = "Integer",paramType = "path"))
    @RequestMapping(value = "queryById/{id}" ,method = RequestMethod.GET)
    public ResponseEntity<JsonResult> getUserById(@PathVariable(value = "id") Integer id){
        JsonResult r = new JsonResult();
        try {
            User user = users.get(id);
            r.setResult(user);
            r.setStatus(ConstantStatus.REQUEST_STATUS_SUCCESS);
        } catch (Exception e) {
            r.setStatus(ConstantStatus.REQUEST_STATUS_ERROR);
            r.setResult(e.getMessage());
            e.printStackTrace();
        }
        return ResponseEntity.ok(r);
    }

    @ApiOperation(value="获取用户列表", notes="获取用户列表")
    @RequestMapping(value = "getusers", method = RequestMethod.GET)
    public ResponseEntity<JsonResult> getUserList(){
        JsonResult r = new JsonResult();
        try {
            List<User> userlist = new ArrayList<User>(users.values());
            r.setResult(userlist);
            r.setStatus(ConstantStatus.REQUEST_STATUS_SUCCESS);
        } catch (Exception e) {
            r.setResult(e.getMessage());
            r.setResult(ConstantStatus.REQUEST_STATUS_ERROR);
            e.printStackTrace();
        }
        return ResponseEntity.ok(r);
    }


    @ApiOperation(value="创建用户", notes="根据User对象创建用户")
    @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
    @RequestMapping(value = "adduser", method = RequestMethod.POST)
    public ResponseEntity<JsonResult> add (@RequestBody User user){
        JsonResult r = new JsonResult();
        try {
            users.put(user.getId(), user);
            r.setResult(user.getId());
            r.setStatus(ConstantStatus.REQUEST_STATUS_SUCCESS);
        } catch (Exception e) {
            r.setResult(e.getClass().getName() + ":" + e.getMessage());
            r.setStatus(ConstantStatus.REQUEST_STATUS_ERROR);
            e.printStackTrace();
        }
        return ResponseEntity.ok(r);
    }

    @ApiOperation(value="删除用户", notes="根据url的id来指定删除用户")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path")
    @RequestMapping(value = "deleteuser/{id}", method = RequestMethod.DELETE)
    public ResponseEntity<JsonResult> delete (@PathVariable(value = "id") Integer id){
        JsonResult r = new JsonResult();
        try {
            users.remove(id);
            r.setResult(id);
            r.setStatus(ConstantStatus.REQUEST_STATUS_SUCCESS);
        } catch (Exception e) {
            r.setResult(e.getClass().getName() + ":" + e.getMessage());
            r.setStatus(ConstantStatus.REQUEST_STATUS_ERROR);
            e.printStackTrace();
        }
        return ResponseEntity.ok(r);
    }

    @ApiOperation(value="更新信息", notes="根据url的id来指定更新用户信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long",paramType = "path"),
            @ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "User")
    })
    @RequestMapping(value = "user/{id}", method = RequestMethod.PUT)
    public ResponseEntity<JsonResult> update (@PathVariable("id") Integer id, @RequestBody User user){
        JsonResult r = new JsonResult();
        try {
            User u = users.get(id);
            u.setUsername(user.getUsername());
            u.setEmail(user.getEmail());
            users.put(id, u);
            r.setResult(u);
            r.setStatus(ConstantStatus.REQUEST_STATUS_SUCCESS);
        } catch (Exception e) {
            r.setResult(e.getClass().getName() + ":" + e.getMessage());
            r.setStatus(ConstantStatus.REQUEST_STATUS_ERROR);
            e.printStackTrace();
        }
        return ResponseEntity.ok(r);
    }

    @ApiIgnore//使用该注解忽略这个API
    @RequestMapping(value = "/hi", method = RequestMethod.GET)
    public String  jsonTest() {
        return " hi you!";
    }

}

Json格式输出类 JsonResult.class

package com.example.demo.bean;

/**
 * @author wyw
 * @Description TODO
 * @date 2019/4/2 16:31
 */
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;
    }
}

实体User.class

public class User { private int id; private String username; private int age; private Date ctm; // Getter Setter }

启动SpringBoot项目，访问 http://localhost:8080/swagger-ui.html