Springboot集成swagger实践

Springboot集成swagger实践

效果展示

源码地址

案例地址

Swagger–pom依赖

  <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
  </dependency>

SwaggerConfig配置类

package com.qiuwei.swagger.config;

import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

/**
 * Swagger配置类
 *
 * @Date: 2020-08-28.
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {


    @Value("${swagger.enable}")
    private Boolean swaggerEnable;


    @Bean
    public Docket createRestApi() {


        /**
         * 根据注解ApiOperation过滤需要生成的API接口
         */

        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        docket.groupName("类别一").apiInfo(apiInfo())
                //是否开启标识
                .enable(swaggerEnable)
                .select()
                //RequestHandlerSelectors.basePackage("com") 扫描对应包下面的接口
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build().globalOperationParameters(parameterBuilder());
        return docket;
    }

    @Bean
    public Docket createRestApi2() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        docket.groupName("类别二").apiInfo(apiInfo())
                .enable(swaggerEnable)
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build().globalOperationParameters(parameterBuilder());
        return docket;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //标题
                .title("书本项目API")
                //描述
                .description("这个是书本项目相关接口文档")
                //条款地址
                .termsOfServiceUrl("http://baidau.com")
                //版本
                .version("1.0")
                .build();
    }


    /**
     * 添加定制化的请求额外参数 如请求头 包含token 可以不配置直接去掉就行
     * @return
     */
    public List<Parameter> parameterBuilder() {
        //添加head参数
        ParameterBuilder tokenPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();
        tokenPar.name("tokenId").description("票").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        pars.add(tokenPar.build());
        return pars;
    }
}

实践案例

Book实例

package com.qiuwei.swagger.bean;

import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import java.io.Serializable;

/**
 * 书本
 *
 * @Author: qiuweib@yonyou.com
 * @Date: 2020-08-28.
 */
@Data
public class Book implements Serializable {
    private static final long serialVersionUID = -6044198948178528507L;

    @ApiModelProperty(value = "书本名称", required = false, example = "不得不说的一二三事")
    private String name;
    @ApiModelProperty(value = "书本价格", required = false, example = "100")
    private String price;
    @ApiModelProperty(value = "书本介绍", required = false, example = "这是成人书籍")
    private String desc;
    @ApiModelProperty(value = "书本类型", required = true, example = "1")
    private Integer type;

}

BookController

package com.qiuwei.swagger.controller;

import com.qiuwei.swagger.bean.Book;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
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.RestController;

import java.util.ArrayList;
import java.util.List;

/**
 * @Author: qiuweib@yonyou.com
 * @Date: 2020-08-28.
 */
@RestController
@Api(tags = "书本类别")
public class BookController {

    /**
     * 1. @Api(): 用于类,表示标识这个类是swagger的资源
     * tags–表示说明
     * value–也是说明，可以使用tags替代
     * 2. @ApiOperation(): 用于方法,表示一个http请求的操作
     * value用于方法描述
     * notes用于提示内容
     * tags可以重新分组
     * 3. @ApiImplicitParam(): 用于方法，表示单独的请求参数
     * 4. @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam
     * name–参数名称
     * value–参数说明
     * dataType–数据类型
     * paramType–参数类型 -- query:请求类型为Json , form :请求为表单类型
     * example–举例说明
     * required-是否必须
     * <p>
     * 5. @ApiModelProperty()用于方法，字段； 表示对model属性的说明或者数据操作更改
     * value–字段说明
     * name–重写属性名字
     * dataType–重写属性类型
     * required–是否必填
     * example–举例说明 (2.2.2版本bug造成example不显示,升级到2.4.0以上即可)
     * hidden–隐藏
     * <p>
     * 查询地址  http://localhost:8080/swagger-ui.html
     *
     * @param book
     * @return
     */


    @GetMapping("book")
    @ApiOperation(value = "查询书本分类", notes = "根据查询条件查询书本")
    public List<Book> listBook(@ApiParam(value = "书本查询条件", required = true) Book book) {
        List<Book> bookList = getBook(book);
        return bookList;
    }


    @PostMapping("add")
    @ApiOperation(value = "添加书本", notes = "添加书")
    public void addBook(@ApiParam(value = "添加书本参数", required = true) @RequestBody Book book) {
        System.out.println("添加书本:" + book.toString());

    }


    /**
     * 没集成数据库 简单模拟列表
     * @param book
     * @return
     */
    private List<Book> getBook(Book book) {
        List<Book> books = new ArrayList<>();

        for (int i = 1; i < 13; i++) {
            Book result = new Book();
            int type = i % 4;
            result.setType(type);
            result.setPrice(String.valueOf(i));
            result.setDesc("这是第" + i + "本书");
            result.setName(i + "禁");

            if (book.getType() == type) {
                books.add(result);
            }
        }
        return books;
    }
}

安全问题

一般开发和测试环境才会开放swagger, 但是在线上环境屏蔽
所以只要动态配置这个参数就可以实现

常用注解说明

1. @Api(): 用于类,表示标识这个类是swagger的资源 
           tags–表示说明 
           value–也是说明，可以使用tags替代
2. @ApiOperation(): 用于方法,表示一个http请求的操作 
           value用于方法描述 
           notes用于提示内容 
           tags可以重新分组
3. @ApiImplicitParam(): 用于方法，表示单独的请求参数 
4. @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam 
           name–参数名称
           value–参数说明 
           dataType–数据类型 
           paramType–参数类型 -- query:请求类型为Json , form :请求为表单类型
           example–举例说明
           required-是否必须
 
5. @ApiModelProperty()用于方法，字段； 表示对model属性的说明或者数据操作更改 
           value–字段说明 
           name–重写属性名字 
           dataType–重写属性类型 
           required–是否必填 
           example–举例说明 (2.2.2版本bug造成example不显示,升级到2.4.0以上即可)
           hidden–隐藏

参考文档 : https://www.jianshu.com/p/6cac7bd21c8f