Swagger 基础使用

Swagger 基础使用

Swagger是最受欢迎的REST APIs文档生成工具之一,原因有:
1、 可以生成一个具有互动性的API控制台，用来快速学习和尝试API；
2、 可以生成客户端SDK代码，用于在不同平台上实现
3、 Swagger文件可以在多个平台上，从代码注释生成
4、 有一个强大的社区
Swagger 文档提供了一个方法，使我们可以用指定的 JSON 或者 YAML 摘要来描述你的 API，包括了比如 names、order 等 API 信息。用 Swagger 文件生成互动的 API 文档是最精简的，它展示了资源、参数、请求、响应。但是它不会提供你的API如何工作的其他任何一个细节。

开源工具
Swagger Codegen: 通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包，docker，node等方式在本地化执行生成, 也可以在Swagger Editor中在线生成。

Swagger UI:提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。

Swagger Editor: 类似于markendown编辑器的编辑Swagger描述文件的编辑器，该编辑支持实时预览描述文件的更新效果, 提供了在线编辑器和本地部署编辑器两种方式。

Swagger Inspector: 感觉和postman差不多，是一个可以对接口进行测试的在线版的postman。比在Swagger UI里面做接口请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。

Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。

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

SpringBoot框架与Swagger应用

1. 引入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>

2. SpringBoot整合Swagger

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket productApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))  //添加ApiOperiation注解的被扫描
                .paths(PathSelectors.any())
                .build();

    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title(”swagger和springBoot整合“).description(”swagger的API文档")
                .version("1.0").build();
    }

}

3. Swagger注解

@Api   可标记一个Controller类作Swagger文档资源

@ApiModel  用于对实体类中参数接受说明

@ApiModelProperty 用于字段, 表示对model属性的说明

@ApiParam 用于Controller中方法的参数说明

@ApiOperation 用在Controller里面的方法上,说明方法作用,定义每一个接口

@ApiResponse和ApiResponses   前者用于方法上,说明接口响应的一些信息,后者组装了多个前者

@ApilmplicitParam和@ApilmplicitParams  用在方法上, 说明单独请求参数

以上是本篇文章的主要内容, 涉及的内容都比较浅显,可以去参考官方文档,里面有更为详细的解释 Swagger官方地址