Swagger2 的简单使用

SpringBoot 整合 Swagger2

在做一些老项目的后期开发时我们会发现，大多数公司在做项目时都是根据项目经理所编写的开发文档来做项目，而后台的程序员根据接口文档来开发接口，这时我们会发现一些问题，由于有一些小改动后代码更改了，但是文档却没有即时更新，造成后期在看文档时，和代码对应不上

之前用的都是由word编写的接口文档，在大部分情况下，会有这么几个问题：

• 接口文档与代码的实时更新
• 接口文档的规范问题
• 接口文档太多，不方便管理

于是Swagger自动生成API文档的工具就出现了，它的优势有：

• Swagger可以自动的生成API文档，并且可以在线测试功能
• Swagger可以与SpringBoot快速整合并使用

Swagger2 使用教程

1、在pom中引入依赖

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

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

2、编写Swagger2的配置类

/**
 * Swagger2 配置类
 * 在与spring boot 集成时，放在与application.java 同级的目录下
 * 通过@Configuration注解，让spring来加载该配置
 * 再通过@EnableSwagger2注解来启动Swagger2
 */
@Configuration
@EnableSwagger2
public class Swagger2 {
    
    

    /**
     * 创建API应用
     * appinfo()增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例，用来控制那些接口暴露给Swagger来展现
     * 本例采用置顶扫描的包路径来定义指定要建立API的目录
     *
     * @return
     */
    @Bean
    public Docket createRestApi() {
    
    
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.Jason.chat"))
                .paths(PathSelectors.any()).build();
        return docket;
    }

    /**
     * 创建改API的基本信息（这些基本信息会展示在文档页面中）
     * 访问地址： http://项目实际地址/swagger-ui.html
     * @return
     */
    public ApiInfo apiInfo() {
    
    
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档")
                .description("简单优雅的restfun风格，https://blog.csdn.net/weixin_43650254")
                .termsOfServiceUrl("https://blog.csdn.net/weixin_43650254")
                .contact("Jason")
                .version("1.0")
                .build();
    }
}

3、用注解实现Swagger自动生成API文档

@Api：用在类上，说明该类的作用。

@ApiOperation：注解来给API增加方法说明。

@ApiImplicitParams : 用在方法上包含一组参数说明。

@ApiImplicitParam：用来注解来给方法入参增加说明。

@ApiResponses：用于表示一组响应

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

• code：数字，例如400

• message：信息，例如"请求参数没填好"

• response：抛出异常的类

@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）

• @ApiModelProperty：描述一个model的属性

注意：@ApiImplicitParam的参数说明：

参数	说明
paramType：指定参数放在哪个地方	header：请求参数放置于Request Header，使用@RequestHeader获取 query：请求参数放置于请求地址，使用@RequestParam获取 path：（用于restful接口）–>请求参数的获取：@PathVariable body：（不常用） form（不常用）
name：参数名
dataType：参数类型
required：参数是否必须传	true | false
value：说明参数的意思
defaultValue：参数的默认值