Spring集成Swagger实现

参考资料

Swagger官网

导语

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。

Swagger介绍

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

Springfox Swagger介绍

Spring 基于swagger规范，可以将基于SpringMVC和Spring Boot项目的项目代码，自动生成JSON格式的描述文件。

pom文件中导入依赖

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

Swagger配置类

@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.any()).build()
            .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("助记宝项目接口文档")
                .description("助记宝项目接口测试,所有的主键都不需要传（牵扯到ID的字段）,创建时间也不传")
                .version("1.0.0")
                .build();
    }
}

springmvc.xml设置

#开放拦截器
<mvc:interceptors>
    <mvc:interceptor>
        <mvc:exclude-mapping path="/swagger*/**"></mvc:exclude-mapping>
    </mvc:interceptor>
</mvc:interceptors>

#开放资源
<mvc:resources mapping="/swagger-ui.html  location="classpath:/META-INF/resources/" />

Swagger使用的注解

@Api注解用于类，表示标识这个类是swagger的资源 。tags表示说明 ，可以标识为类名。

@ApiOperation注解用于方法说明。value为简要描述,notes为全面描述,hidden=true Swagger将不显示该方法，默认为false。

@ApiParam注解用于方法参数，对方法参数进行了说明。

@ApiIgnore注解用于类、参数、方法上，注解后将不在Swagger UI中显示。

@ApiImplicitParam注解用于对参数说明。

@ApiImplicitParams() 注解用于方法，包含多个 @ApiImplicitParam。

@ApiResponse注解用于响应配置。

@ApiModel注解用于描述一个Model的信息。

转载于:https://www.cnblogs.com/feiqiangsheng/p/10998289.html