@Api @ApiOperation @ApiModel @ApiModelProperty——Swagger常用注解-蒲公英云

@API

@ApiOperation

@ApiModel()

@ApiModelProperty()

@ApiParam

访问地址

依赖

配置类

SpringSecurity中配置

省流：

@ApiModel 和 @ApiModelProperty 常用于实体类中，如下

@ApiModel("查询机构入参")
public class OrgDTO{
    @ApiModelProperty(value = "机构号")
    private String orgCode;
    @ApiModelProperty(value = "名字")
    private String name;
}

@Api 和 @ApiOperation 常用于 Controller 中，如下

@Api(tags = "购物车接口")
public class ShoppingController{
    @ApiOperation("购物车删除")
    @GetMapping("/t1")
    public void t1(){}
    @ApiOperation("购物车新增")
    @PostMapping("/t2")
    public void t2(){}
}

正文：

@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

依赖

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

访问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（完整版）

========================分割线=======================

紫薯布丁

io.springfox
springfox-swagger-ui
2.9.2

io.springfox
springfox-swagger2
2.9.2

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;

/**

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();
}
}

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

@ApiModel(“查询机构入参”)
public class OrgDTO{

@ApiModelProperty(value = “机构号”)
private String orgCode;

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

}

@Api(tags = “购物车接口”)
public class ShoppingController{

@ApiOperation(“购物车删除”)
@GetMapping(“/t1”)
public void t1(){}

@ApiOperation(“购物车新增”)
@PostMapping(“/t2”)
public void t2(){}
}