SpringBoot（六） SpringBoot整合Swagger2（自动化生成接口文档）

一：在上篇文章pom增加依赖：

        <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配置类

其实这个配置类，只要了解具体能配置哪些东西就好了，毕竟这个东西配置一次之后就不用再动了。 特别要注意的是里面配置了api文件也就是要放在controller包的路径，不然生成的文档扫描不到接口。

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;
 
/**
 * @author zh
 * @classname cn.saytime.swgger2
 * @description
 * @date 2017-07-10 22:12:31
 */
@configuration
public class swagger2 {
 
    @bean
    public docket createrestapi() {
        return new docket(documentationtype.swagger_2)
                .apiinfo(apiinfo())
                .select()
                .apis(requesthandlerselectors.basepackage("cn.saytime.web"))
                .paths(pathselectors.any())
                .build();
    }
    
    private apiinfo apiinfo() {
        return new apiinfobuilder()
                .title("springboot利用swagger构建api文档")
                .description("简单优雅的restfun风格，http://blog.csdn.net/saytime")
                .termsofserviceurl("http://blog.csdn.net/saytime")
                .version("1.0")
                .build();
    }

}

usercontroller.class:

package com.demo.web;
import java.util.list;

import org.springframework.beans.factory.annotation.autowired;
import org.springframework.http.responseentity;
import org.springframework.web.bind.annotation.pathvariable;
import org.springframework.web.bind.annotation.requestbody;
import org.springframework.web.bind.annotation.requestmapping;
import org.springframework.web.bind.annotation.requestmethod;
import org.springframework.web.bind.annotation.restcontroller;

import com.demo.bean.jsonresult;
import com.demo.mapper.user;
import com.demo.service.userservice;
 
@restcontroller
public class usercontroller {
 
    @autowired
    private userservice userservice;
 
    @requestmapping(value = "user/{id}", method = requestmethod.get)
    public responseentity<jsonresult> getuserbyid (@pathvariable(value = "id") integer id){
        jsonresult r = new jsonresult();
        try {
            user user = userservice.getuserbyid(id);
            r.setresult(user);
            r.setstatus("ok");
        } catch (exception e) {
            r.setresult(e.getclass().getname() + ":" + e.getmessage());
            r.setstatus("error");
            e.printstacktrace();
        }
        return responseentity.ok(r);
    }
 
    /**
     * 查询用户列表
     * @return
     */
    @requestmapping(value = "users", method = requestmethod.get)
    public responseentity<jsonresult> getuserlist (){
        jsonresult r = new jsonresult();
        try {
            list<user> users = userservice.getuserlist();
            r.setresult(users);
            r.setstatus("ok");
        } catch (exception e) {
            r.setresult(e.getclass().getname() + ":" + e.getmessage());
            r.setstatus("error");
            e.printstacktrace();
        }
        return responseentity.ok(r);
    }
 

 
}

 

application.class 加上注解@enableswagger2 表示开启swagger:

@enableautoconfiguration
@springbootapplication
@mapperscan("com.demo.mapper")
@enableswagger2
public class springbootstartapplication {

    public static void main(string[] args) {
        springapplication.run(springbootstartapplication.class, args);
    }
    
}

其他类没有贴出，还是沿用上一篇文章的类。

项目结构：

 

 

四、swagger2文档

启动springboot项目，访问 

 

 

具体里面的内容以及接口测试，应该一看就懂了。这里就不一一截图了。

五、swagger注解
swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

@api：修饰整个类，描述controller的作用
@apioperation：描述一个类的一个方法，或者说一个接口
@apiparam：单个参数描述
@apimodel：用对象来接收参数
@apiproperty：用对象接收参数时，描述对象的一个字段
@apiresponse：http响应其中1个描述
@apiresponses：http响应整体描述
@apiignore：使用该注解忽略这个api
@apierror ：发生错误返回的信息
@apiimplicitparam：一个请求参数
@apiimplicitparams：多个请求参数

二：使用swagger注解之后的usercontroller:

package com.demo.web;
import java.util.arraylist;
import java.util.collections;
import java.util.hashmap;
import java.util.list;
import java.util.map;

import org.springframework.http.responseentity;
import org.springframework.web.bind.annotation.pathvariable;
import org.springframework.web.bind.annotation.requestbody;
import org.springframework.web.bind.annotation.requestmapping;
import org.springframework.web.bind.annotation.requestmethod;
import org.springframework.web.bind.annotation.restcontroller;

import com.demo.bean.jsonresult;
import com.demo.mapper.user;

import io.swagger.annotations.apiimplicitparam;
import io.swagger.annotations.apiimplicitparams;
import io.swagger.annotations.apioperation;
import springfox.documentation.annotations.apiignore;
 
/**
 * @author zh
 * @classname cn.saytime.web.usercontroller
 * @description
 */
@restcontroller
public class usercontroller {
 
    // 创建线程安全的map
    static map<integer, user> users = collections.synchronizedmap(new hashmap<integer, user>());
 
    /**
     * 根据id查询用户
     * @param id
     * @return
     */
    @apioperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
    @apiimplicitparam(name = "id", value = "用户id", required = true, datatype = "integer", paramtype = "path")
    @requestmapping(value = "user/{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("ok");
        } catch (exception e) {
            r.setresult(e.getclass().getname() + ":" + e.getmessage());
            r.setstatus("error");
            e.printstacktrace();
        }
        return responseentity.ok(r);
    }
 
    /**
     * 查询用户列表
     * @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());
            r.setresult(userlist);
            r.setstatus("ok");
        } catch (exception e) {
            r.setresult(e.getclass().getname() + ":" + e.getmessage());
            r.setstatus("error");
            e.printstacktrace();
        }
        return responseentity.ok(r);
    }
 
    /**
     * 添加用户
     * @param user
     * @return
     */
    @apioperation(value="创建用户", notes="根据user对象创建用户")
    @apiimplicitparam(name = "user", value = "用户详细实体user", required = true, datatype = "user")
    @requestmapping(value = "user", 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("ok");
        } catch (exception e) {
            r.setresult(e.getclass().getname() + ":" + e.getmessage());
            r.setstatus("error");
 
            e.printstacktrace();
        }
        return responseentity.ok(r);
    }
 
    /**
     * 根据id删除用户
     * @param id
     * @return
     */
    @apioperation(value="删除用户", notes="根据url的id来指定删除用户")
    @apiimplicitparam(name = "id", value = "用户id", required = true, datatype = "long", paramtype = "path")
    @requestmapping(value = "user/{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("ok");
        } catch (exception e) {
            r.setresult(e.getclass().getname() + ":" + e.getmessage());
            r.setstatus("error");
 
            e.printstacktrace();
        }
        return responseentity.ok(r);
    }
 
    /**
     * 根据id修改用户信息
     * @param user
     * @return
     */
    @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.setage(user.getage());
            users.put(id, u);
            r.setresult(u);
            r.setstatus("ok");
        } catch (exception e) {
            r.setresult(e.getclass().getname() + ":" + e.getmessage());
            r.setstatus("error");
 
            e.printstacktrace();
        }
        return responseentity.ok(r);
    }
 
    @apiignore//使用该注解忽略这个api
    @requestmapping(value = "/hi", method = requestmethod.get)
    public string  jsontest() {
        return " hi you!";
    }

}