Spring Boot 项目中使用Swagger2的示例

本文介绍了spring boot 项目中使用swagger2的示例，分享给大家，具体如下：

添加swagger2依赖

在pom.xml中加入swagger2的依赖

<dependency>
  <groupid>io.springfox</groupid>
  <artifactid>springfox-swagger2</artifactid>
  <version>2.2.2</version>
</dependency>
<dependency>
  <groupid>io.springfox</groupid>
  <artifactid>springfox-swagger-ui</artifactid>
<version>2.2.2</version>
</dependency>

创建swagger2配置类

在application.java同级创建swagger2的配置类swagger2。

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.spi.documentationtype;
import springfox.documentation.spring.web.plugins.docket;
import springfox.documentation.swagger2.annotations.enableswagger2;

@configuration
@enableswagger2
public class swagger2 {
  @bean
  public docket createrestapi() {
    return new docket(documentationtype.swagger_2)
        .apiinfo(apiinfo())
        .select()
        .apis(requesthandlerselectors.basepackage("你自己的外部接口包名称"))
        .paths(pathselectors.any())
        .build();
  }

  private apiinfo apiinfo() {
    return new apiinfobuilder()
        .title("词网neo4j restful apis")
        .description("the neo4j restful apis description/")
        .termsofserviceurl("")
        .contact("李庆海")
        .version("5.0")
        .build();
  }
}

添加文档内容

在完成了上述配置后，其实已经可以生产文档内容，但是这样的文档主要针对请求本身，而描述主要来源于函数等命名产生，对用户并不友好，我们通常需要自己增加一些说明来丰富文档内容。

import io.swagger.annotations.api;
import io.swagger.annotations.apioperation;
import io.swagger.annotations.apiparam;
/**
 * 系统用户controller
 * 
 * @author 李庆海
 *
 */
@api(value = "系统用户接口", tags = "系统管理")
@restcontroller
@requestmapping("/v3/edu/users")
public class usercontroller {

  @autowired
  private userservice userservice;

  /**
   * 添加用户，注册
   * 
   * @param loginname
   *      登录账号
   * @param username
   *      用户名称
   * @param password
   *      登录密码
   * @param roleid
   *      用户角色
   * @return
   * @throws resourceexistsexception
   */
  @apioperation(value = "添加用户")
  @postmapping("/")
  public jsonresult create(
      @apiparam(name = "loginname", value = "登录账号", required = true) @requestparam(required = true) @requestbody string loginname,
      @apiparam(name = "username", value = "用户名称", required = true) @requestparam(required = true) @requestbody string username,
      @apiparam(name = "password", value = "登录密码", required = true) @requestparam(required = true) @requestbody string password,
      @apiparam(name = "roleid", value = "用户角色编号", required = true) @requestparam(required = true) @requestbody string roleid)
      throws resourceexistsexception {
    boolean exists = this.userservice.exists(loginname);
    if (exists) {
      throw new resourceexistsexception(loginname);
    }
    user user = userservice.create(loginname, password, username, roleid);
    return new jsonresult(user);
  }
}

查看api

启动spring boot程序，访问：http://localhost:8080/swagger-ui.html

api文档访问与调试

swagger除了查看接口功能外，还提供了调试测试功能，我们可以点击上图中右侧的model schema（黄色区域：它指明了数据结构），此时value中就有了user对象的模板，我们只需要稍适修改，点击下方try it out！按钮，即可完成了一次请求调用！可以通过几个get请求来验证之前的post请求是否正确。

以上就是本文的全部内容，希望对大家的学习有所帮助，也希望大家多多支持。