Spring Boot集成springfox-swagger2构建restful API的方法教程

前言

之前跟大家分享了spring mvc集成springfox-swagger2构建restful api，简单写了如何在springmvc中集成swagger2。这边记录下在springboot中如何集成swagger2。其实使用基本相同。

方法如下：

首先还是引用相关jar包。我使用的maven，在pom.xml中引用相关依赖(原来我使用的是2.2.0的，现在使用2.4.0的)：

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

第二步就是创建swagger的配置类：

这个配置类和springmvc的写法完全一致。为了区分我又重命名一个。

package com.xingguo.springboot;

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

 @bean
 public docket builddocket(){
  return new docket(documentationtype.swagger_2)
    .apiinfo(buildapiinf())
    .select()
    .apis(requesthandlerselectors.basepackage("com.xingguo.springboot.controller"))
    .paths(pathselectors.any())
    .build();
 }

 private apiinfo buildapiinf(){
  return new apiinfobuilder()
     .title("xingguo大标题")
     .description("springboot swagger2")
     .termsofserviceurl("http://blog.csdn.net/u014231523网址链接")
     .contact(new contact("diaoxingguo", "http://blog.csdn.net/u014231523", "[e-mail]"))
     .build();

 }

}

在原来2.2.0的版本中使用new apiinfo()的方法已经过时，使用new apiinfobuilder()进行构造，需要什么参数就添加什么参数。当然也可以什么都添加。如：

private apiinfo buildapiinfo(){
 return new apiinfobuilder().build();
}

那么页面显示的效果如图：

使用new apiinfobuilder().build()；

添加属性：

点击apiinfobuilder.java的源码可以看到相关方法使用。

第三步就是在自己的controller添加相关的注解：

原来使用在类上使用@controller，现在可以使用@restcontroller，然后方法的@responsebody就可以不用写了，因为@restcontroller的注解接口上已经添加了，要求版本在4.0.1之后。

@target(elementtype.type)
@retention(retentionpolicy.runtime)
@documented
@controller
@responsebody
public @interface restcontroller {

 /**
  * the value may indicate a suggestion for a logical component name,
  * to be turned into a spring bean in case of an autodetected component.
  * @return the suggested component name, if any
  * @since 4.0.1
  */
 string value() default "";

}

常用的注解如下：

      - @api()用于类名

      - @apioperation()用于方法名

      - @apiparam()用于参数说明

      - @apimodel()用于实体类

      - @apimodelproperty用于实体类属性

更加详细的含义可以参考官方说明wiki

下面会用代码和示例图说明。

第四部就是在启动项目在浏览器上输入url:

http://{ip}:{port}/swagger-ui.html#/

我在application.properties中设置的自己的端口号为9090(如果不设置，默认为8080)

server.port=9090

所以我的url是：http://localhost:9090/swagger-ui.html

如图：

这里会把相应包下的所有controller按类进行显示。

我们看下其中一个类usercontroller.java,（请忽略业务逻辑，只看注解）

package com.xingguo.springboot.controller;

import io.swagger.annotations.api;
import io.swagger.annotations.apioperation;
import io.swagger.annotations.apiparam;

import javax.annotation.resource;

import org.springframework.web.bind.annotation.getmapping;
import org.springframework.web.bind.annotation.postmapping;
import org.springframework.web.bind.annotation.requestbody;
import org.springframework.web.bind.annotation.responsebody;
import org.springframework.web.bind.annotation.restcontroller;

import com.xingguo.springboot.model.user;
import com.xingguo.springboot.service.userservice;

/**
 * created by diaoxingguo on 2016/10/24.
 */
@api(value="用户controller",description="用户操作",tags={"用户操作接口"})
@restcontroller
public class usercontroller {

 @resource
 private userservice userservice;

 @apioperation("获取用户信息")
 @getmapping("/getuserinfo")
 public user getuserinfo(@apiparam(name="id",value="用户id",required=true) long id,@apiparam(name="username",value="用户名") string username) {
  user user = userservice.getuserinfo();
  return user;
 }


 @apioperation("更改用户信息")
 @postmapping("/updateuserinfo")
 public int updateuserinfo(@requestbody @apiparam(name="用户对象",value="传入json格式",required=true) user user){
  int num = userservice.updateuserinfo(user);
  return num;
 }

 @apioperation("添加用户信息")
 @postmapping("/saveuser")
 public string saveuser(@requestbody @apiparam(name="user",value="json fromat",required=true) user user) {
  userservice.saveuser(user);
  return "success";
 }
}

这里说明下，在使用对象作为参数时，可以在对象上添加相应的注解，用户页面显示。

如：

package com.xingguo.springboot.model;

import io.swagger.annotations.apimodel;
import io.swagger.annotations.apimodelproperty;

import java.util.list;

/**
 * created by diaoxingguo on 2016/10/24.
 */
@apimodel(description="用户对象user")
public class user {
 @apimodelproperty(value="用户名",name="username")
 private string username;
 @apimodelproperty(value="状态",name="state",required=true)
 private integer state;
 private string password;
 private string nickname;
 private integer isdeleted;

 private string[] ids;
 private list<string> idlist;

 public string getusername() {
  return username;
 }

 public void setusername(string username) {
  this.username = username;
 }

 public integer getstate() {
  return state;
 }

 public void setstate(integer state) {
  this.state = state;
 }

 public string getpassword() {
  return password;
 }

 public void setpassword(string password) {
  this.password = password;
 }

 public string[] getids() {
  return ids;
 }

 public void setids(string[] ids) {
  this.ids = ids;
 }

 public list<string> getidlist() {
  return idlist;
 }

 public void setidlist(list<string> idlist) {
  this.idlist = idlist;
 }

 public string getnickname() {
  return nickname;
 }

 public void setnickname(string nickname) {
  this.nickname = nickname;
 }

 public integer getisdeleted() {
  return isdeleted;
 }

 public void setisdeleted(integer isdeleted) {
  this.isdeleted = isdeleted;
 }


}

显示的效果如图：

看上图红框的部分，其中一个是json格式的点击就可以获取参数格式。

第二张中可以看到字段相应的注释和是否必填。

如果在字段上添加注释@apimodelproperty(required=true)就是必填（默认是false），相应的页面optional标识也会消失，标识这个字段必填。

点击下面的try it out按钮就可以进行调试。

在使用单个参数时，如上面代码中的getuserinfo（）方法，对应的效果图如下：

这里如果是添加required=true， @apiparam(required=true)则会在页面上显示required的标识。同样默认为false。

其他的使用方式可以自己动手试试。

总结

以上就是这篇文章的全部内容了，希望本文的内容对大家的学习或者工作能带来一定的帮助，如有疑问大家可以留言交流，谢谢大家对的支持。