Swagger

最新推荐文章于 2025-11-23 07:59:38 发布

原创最新推荐文章于 2025-11-23 07:59:38 发布 · 328 阅读

0 ·

CC 4.0 BY-SA版权

框架专栏收录该内容

8 篇文章

订阅专栏

本文详细介绍Swagger的组件及其在Java和JavaScript中的实现，包括Swagger-tools、Swagger-core、Swagger-js、Swagger-ui、Swagger-codegen等，解释了如何使用这些工具生成API文档，以及在Spring框架中集成Swagger的具体步骤。

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

Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger2.0文档等功能。
Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF…)、Servlets和Play框架进行集成。
Swagger-js: 用于JavaScript的Swagger实现。 Swagger-node-express:
Swagger模块，用于node.js的Express web应用框架。
Swagger-ui：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。
Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码。

API注解

@Api

用在类上，该注解将一个Controller（Class）标注为一个swagger资（API）。在默认情况下，Swagger-Core只会扫描解析具有@Api注解的类，而会自动忽略其他类别资源（JAX-RS endpoints，Servlets等等）的注解。该注解包含以下几个重要属性

tags API分组标签。具有相同标签的API将会被归并在一组内展示。
value 如果tags没有定义，value将作为Api的tags使用
description API的详细描述，在1.5.X版本之后不再使用，但实际发现在2.0.0版本中仍然可以使用

@ApiOperation

在指定的（路由）路径上，对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。此注解的属性有：

value 对操作的简单说明，长度为120个字母，60个汉字。
notes 对操作的详细说明。
httpMethod HTTP请求的动作名，可选值有：“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” AND “PATCH”。
code 默认为200，有效值必须符合标准的HTTP Status Code Definitions。

@ApiImplicitParams

用在方法上，注解ApiImplicitParam的容器类，以数组方式存储。

@ApiImplicitParam

对API的单一参数进行注解。虽然注解@ApiParam同JAX-RS参数相绑定，但这个@ApiImplicitParam注解可以以统一的方式定义参数列表，也是在Servelet及非JAX-RS环境下，唯一的方式参数定义方式。注意这个注解@ApiImplicitParam必须被包含在注解@ApiImplicitParams之内。可以设置以下重要参数属性：

name 参数名称
value 参数的简短描述
required 是否为必传参数
dataType 参数类型，可以为类名，也可以为基本类型（String，int、boolean等）
paramType 参数的传入（请求）类型，可选的值有path, query, body, header or form

@ApiParam

增加对参数的元信息说明。这个注解只能被使用在JAX-RS 1.x/2.x的综合环境下。其主要的属性有

required 是否为必传参数，默认为false
value 参数简短说明

@ApiResponses

注解@ApiResponse的包装类，数组结构。即使需要使用一个@ApiResponse注解，也需要将@ApiResponse注解包含在注解@ApiResponses内。

@ApiResponse
描述一个操作可能的返回结果。当REST API请求发生时，这个注解可用于描述所有可能的成功与错误码。可以用，也可以不用这个注解去描述操作的返回类型，但成功操作的返回类型必须在@ApiOperation中定义。如果API具有不同的返回类型，那么需要分别定义返回值，并将返回类型进行关联。但Swagger不支持同一返回码，多种返回类型的注解。注意：这个注解必须被包含在@ApiResponses注解中。

code HTTP请求返回码。有效值必须符合标准的HTTP Status Code Definitions。
message 更加易于理解的文本消息
response 返回类型信息，必须使用完全限定类名，比如“com.willem.user.User.class”。
responseContainer 如果返回类型为容器类型，可以设置相应的值。有效值为 “List”, “Set” or “Map”，其他任何无效的值都会被忽略

Model注解

对于Model的注解，Swagger提供了两个：@ApiModel及@ApiModelProperty，分别用以描述Model及Model内的属性。

@ApiModel
描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
提供对Swagger model额外信息的描述。在标注@ApiOperation注解的操作内，所有的类将自动被内省（introspected），但利用这个注解可以做一些更加详细的model结构说明。主要属性有：

value model的别名，默认为类名
description model的详细描述

@ApiModelProperty

描述一个model的属性对model属性的注解，主要的属性值有：

value 属性简短描述
example 属性的示例值
required 是否为必须值

将各个系统的API数据集中

客户端
将这个放到你的config启动，注意这里我用了一个占位符获取当前文档的名称，避免写死后续可能添加其他模块
pom文件中添加以下依赖

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

/**
 * @program: container
 * @description: SwaggerConfig
 * @author: willem
 * @create: 2020-03-04 13:30:23
 */
@ConditionalOnClass(value = {Swagger.class})
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Value("${spring.application.name}")
    private String applicationName;
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.**.**.controller"))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(parameters());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(applicationName+"接口文档")
                .description(applicationName+"接口文档")
                .contact(new Contact("***", "https://***.***.com", "***@163.com"))
                .version("2.0")
                .build();
    }

    private List<Parameter> parameters() {
        ParameterBuilder parameterBuilder = new ParameterBuilder();
        List<Parameter> parameters = new ArrayList<>();
        parameterBuilder.name("session")
                .description("session")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false).build();
        parameters.add(parameterBuilder.build());
        return parameters;
    }
}

网关Zuul
zuul的pom文件中添加以下依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>2.9.2</version>
</dependency>

在zuul的config中添加如下配置，注意这里有个apiNames是所有的分组服务名，避免写死，直接从配置文件读取

SwaggerResource有三个参数，

第一个参数：名称，也就是之前那个下拉框的选择条名称
第二个参数：url，就是访问具体系统swagger的链接
第三个参数：version ，就是swagger的版本

/**
 * @program: container
 * @description: DocumentationConfig
 * @author: willem
 * @create: 2020-03-05 17:01:23
 */
@EnableSwagger2
@Component
@Primary
public class DocumentationConfig implements SwaggerResourcesProvider {

    @Value("${rest.api.names}")
    private String[] apiNames;

    @Override
    public List<SwaggerResource> get() {
        List resources = new ArrayList<>();
        if (apiNames != null) {
            Arrays.stream(apiNames).forEach(s ->
                    resources.add(swaggerResource(s, "/" + s + "/v2/api-docs", "2.0"))
            );
        }
        return resources;
    }

    private SwaggerResource swaggerResource(String name, String location, String version) {
        SwaggerResource swaggerResource = new SwaggerResource();
        swaggerResource.setName(name);
        swaggerResource.setLocation(location);
        swaggerResource.setSwaggerVersion(version);
        return swaggerResource;
    }
}