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

r囧r小猫 2024-03-24 11:29 65阅读 0赞

**目录**

@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)][ApiModel _ ApiModelProperty _ - _ _juejin.cn]

[SpringBoot整合Swagger2（完整版）][SpringBoot_Swagger2]

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

紫薯布丁

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

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

@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()\{\}  
\}

[ApiModel _ ApiModelProperty _ - _ _juejin.cn]: https://juejin.cn/post/7109835493952454693
[SpringBoot_Swagger2]: https://blog.csdn.net/qq_40205116/article/details/105200104