@Api @ApiOperation @ApiModel @ApiModelProperty——Swagger常用注解

@API

通常用在Controller上。表明是swagger资源。

@Api(tags = "购物车接口")
public class ShoppingController{}

@Api(tags = {"对外：员工信息对接接口","对内：员工信息接口"})
public class StaffController{}

@API拥有两个属性：value、tags。生成的api文档会根据tags分类，即该controller中所有接口生成的文档都会在此tags下。tags可以有多个值，value的作用类似tags，但是不能有多个值。一般用tags，源码里说如果没有用tags，就会把value的值给tags。

//If tags is not used,this value will be used to set the tag for the operations described by this resource. Otherwise, the value will be ignored.
 String value() default "";

 //Tags can be used for logical grouping of operations by resources or any other qualifier.
 String[] tags() default {""};

@ApiOperation

用在方法上

@ApiOperation("购物车分页查询")
@GetMapping("/t1")
public void t1(){}

属性：

value 简短描述，一般用来做标题
notes 详细描述，一般用来做解释
tags 分组，对应@Api的tags，如果@Api的tags用了多个，方法会根据这个来分组

@ApiModel()

一般用在实体类上

@ApiModel("机构")
public class OrgEntity{}

@ApiModel("查询机构入参")
public class QueryOrgDTO{}

@ApiModel("查询机构出参")
public class QueryOrgVO{}

@ApiModelProperty()

一般用在字段上

@ApiModelProperty(value = "主键")
private String id;

@ApiModelProperty(value = "名字")
private String name;

required 是否必填，该字段后面会有一个红色的星号

@ApiParam

用在参数上，
name 参数名
value 参数说明
required 是否必填

访问地址

/swagger-ui.html

http://localhost:8080/项目名(默认无)/swagger-ui.html

如果配置了，如下，那地址就是：http://localhost:8050/aliba/swagger-ui.html

server:
  port: 8050
  servlet:
    context-path: /aliba

依赖

    io.springfox
    springfox-swagger-ui
    2.9.2


    io.springfox
    springfox-swagger2
    2.9.2

访问swagger的页面需要上面两个依赖。

配置类

无此配置类没关系，可以打开swagger页面。 

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.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;

/**
 1. swagger配置类
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //是否开启 (true 开启  false隐藏。生产环境建议隐藏)
                //.enable(false)
                .select()
                //扫描的路径包,设置basePackage会将包下的所有被@Api标记类的所有方法作为api
                .apis(RequestHandlerSelectors.basePackage("com.**.controller"))
                //指定路径处理PathSelectors.any()代表所有的路径
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //设置文档标题(API名称)
                .title("SpringBoot中使用Swagger2接口规范")
                //文档描述
                .description("接口说明")
                //服务条款URL
                .termsOfServiceUrl("http://localhost:8080/")
                //版本号
                .version("1.0.0")
                .build();
    }
}

SpringSecurity中配置

Spring Boot项目中集成了Spring Security，接口会被拦截，需要在Spring Security的配置类中重写configure方法，对接口进行过滤

@Override
public void configure(WebSecurity web) throws Exception {
    web.ignoring()
            .antMatchers("/swagger-ui.html")
            .antMatchers("/v2/**")
            .antMatchers("/swagger-resources/**");
}

参考

ApiModel 和 ApiModelProperty 注解详解 - 掘金 (juejin.cn)

SpringBoot整合Swagger2（完整版）