springboot项目集成swagger的实践

一、认识Swagger

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

作用：

1. 接口的文档在线自动生成。

2. 功能测试。

Swagger是一组开源项目，其中主要要项目如下：

1. Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。

2. Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF...)、Servlets和Play框架进行集成。

3. Swagger-js: 用于JavaScript的Swagger实现。

4. Swagger-node-express: Swagger模块，用于node.js的Express web应用框架。

5. Swagger-ui：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。

6. Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码。

二、引入pom文件

<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger2</artifactId>
 <version>${swagger.version}</version>
</dependency>

<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger-ui</artifactId>
 <version>${swagger.version}</version>
</dependency>

三、添加config配置文件

加上注解@EnableSwagger2 表示开启Swagger

注意：配置了api文件也就是controller包的路径，不然生成的文档扫描不到接口

@EnableSwagger2
@Configuration
public class SwaggerConfig {

  @Bean
  public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.kemai.module.controller"))
        .paths(PathSelectors.any())
        .build();
  }

  private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
        .title("蜗健大数据平台api文档")
        .description("平台接口，符合restful风格")
        .version("1.0")
        .build();
  }

四、配置controller接口

/**
	 * 根据用户ID查询
	 * @param userId
	 */
@ApiOperation(value = "用户查询")
@PutMapping(value = "/User/{userId}")
public void updateUserCount(@ApiParam(value = "用户ID") 
            @PathVariable(value = "userId")Integer userId) throws Exception {
		 userService.findUser(userId);
	}

访问地址：

启动SpringBoot项目，访问http://localhost:8080/swagger-ui.html

8080改为自己设置的端口号。

整体配置页面的显示效果

swagger中会详细按照接口中写的注解，显示在api接口文档中。

填入相关参数执行，可以进行接口测试。

五、Swagger注解

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数

Swagger扫描解析得到的是一个json文件，但是对于用户来说看这种文件不是很

方便，但是通过swagger-ui，可以友好的展示解析得到的接口说明内容。

springboot项目集成swagger的实践

猜你喜欢