spring-boot swagger2

发表于 2019-01-14 更新于 2019-01-15 阅读次数：本文字数： 3.6k 阅读时长 ≈ 3 分钟

注意，如果不指定请求的 Method 会把所有支持的 Method 都自动显示出来，GET，POST，HEAD，DELETE…等等

添加插件配置

// https://mvnrepository.com/artifact/io.springfox/springfox-swagger2
compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'
// https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui
compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'

Swagger2 配置

在主应用同级目录下创建 swagger2Config.java 内容如下，根据实际情况修改

package com.example.demo;

import com.google.common.base.Predicate;
import com.google.common.base.Predicates;
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 swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("public-api")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                .paths(paths())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("REST API 文档演示")
                .description("Gradle 构建 Spring boot项目 集成 mybatis 使用 pagehelper 插件")
                .termsOfServiceUrl("http://zhengjunblog.top")
                .version("1.0")
                .build();
    }

    //Here is an example where we select any api that matches one of these paths
    private Predicate<String> paths() {
        return Predicates.or(
                PathSelectors.regex("/api/.*"),
                PathSelectors.regex("/business/.*"));
    }

}

apis() 定义包含的类(controller and model classes)。这个是包括所有的 RequestHandlerSelectors.any()，可通过包名，类名来定制
paths() 通过路径映射来定制。

实体类的注释

package com.example.demo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(value="Topic 对象",description="Topic 对象类的相关描述")
public class Topic {

    @ApiModelProperty(value="Topic id",name="id",example="1",required=true)
    private String id;
    @ApiModelProperty(value="Topic string",name="topic",example="java",required=true)
    private String topic;
    @ApiModelProperty(value="Topic description",name="descript",example="a java description",required=true)
    private String descript;
    ...
  }

@Configuration 注解 让Spring来加载该类配置
@EnableSwagger2 注解 启用Swagger2。

.apis(RequestHandlerSelectors.basePackage("com.example.demo.Controller"))
待扫描的接口包，Swagger会扫描该包下所有Controller定义的API ，并生成API文档（除了被@ApiIgnore指定的请求）。

@ApiImplicitParams、@ApiImplicitParam 注解来给参数增加说明
@Api：用在类上，说明该类的作用
@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”；其他参数可参考源码；
@ApiImplicitParams：用在方法上包含一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
  paramType：参数放在哪个地方
    header-->请求参数的获取：@RequestHeader
    query-->请求参数的获取：@RequestParam
    path（用于restful接口）-->请求参数的获取：@PathVariable
    body（不常用）
    form（不常用）
  name：参数名
  dataType：参数类型
  required：参数是否必须传
  value：参数的意思
  defaultValue：参数的默认值
@ApiResponses：用于表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类
@ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty()用于方法，字段； 表示对model属性的说明或者数据操作更改
  value–字段说明
  name–重写属性名字
  dataType–重写属性类型
  required–是否必填
  example–举例说明
  hidden–隐藏