ApiOperation和ApiParam注解依赖的安装和使用以及注意事项说明

ApiOperation和ApiParam注解依赖的安装

如果要使用@ApiOperation注解，需要引入swagger，而不是引入OpenAPI

引入依赖

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

启动类设置注解启动

这样就可以在controller里使用 @ApiOperation 注解了，通过浏览器访问 http://localhost:8088/swagger-ui.html

ApiOperation和ApiParam注解的使用

常用的有

• @Api 
• @ApiOperation 
• @ApiParam

Api

ApiOperation和ApiParam

@ApOperation 不是spring自带的注解是swagger里面的 com.wordnik.swagger.annotations.ApiOperation;

详细介绍： @ApiOperation 和 @ApiParam 为添加的Controller接口相关注解，个参数说明如下：

@ApiOperation( value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”；

其他参数可参考源码；

@ApiParam( required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”

其中部分参数可以根据需求增加或者删除

@ApiParam 的使用方式和@RequestParam 有点像, 并且可以像如下这样使用

public DataResult<ZonesEiaPlanPageInfoVO> detail(@RequestParam @ApiParam(name = "id", value = "主键") String id) {}

拓展

实际项目中非常需要写文档，提高Java服务端和Web前端以及移动端的对接效率。

由于我们在开发中接口众多而且细节复杂（需要考虑不同的HTTP请求类型，HTTP头部信息，HTTP请求内容等）高质量地创建这份文档本身就是一件复杂的事情。

随着时间的前进和技术的推移，不断修改接口实现的时候都必须同步修改接口文档，而接口文档和代码又处于不同时空的两个地方。

注意事项

如果说打不开那个swagger网页

• 检查是否使用了@EnableSwagger2
• 是否有自定义了api前缀

• 是否有拦截器拦截

总结

以上为个人经验，希望能给大家一个参考，也希望大家多多支持脚本之家。