Swagger的简单使用

介绍

现如今前后端分离的时代，前端常抱怨后端给的接口文档与实际情况不一致，后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新，swagger则应运而生，它的优点如下：

• 号称世界上最流行的API框架
• API 文档 与API同步更新
• 直接运行，在线测试API
• 官网：https://swagger.io/
• 访问测试 ：http://localhost:8080/swagger-ui.html ，可以看到swagger的界面；

使用

1. 导入依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

2. 配置

package com.lxs.swagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

@Configuration
@EnableSwagger2//开启swagger2
public class SwaggerConfig {

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .groupName("AAA")//分组的名字
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.lxs.swagger.controller"))//配置扫描指定的包
                .build();
    }
    //配置Swagger信息apiInfo
    private ApiInfo apiInfo(){
        //作者信息
        Contact DEFAULT_CONTACT = new Contact("***", "https://blog.csdn.net/weixin_45954737", "****");
        return new ApiInfo(
                "**的API文档",//标题
                "这人有点6",//描述
                "v1.0",//版本
                "https://blog.csdn.net/weixin_45954737",//团队链接
                DEFAULT_CONTACT,//联系人信息
                "Apach  2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",//许可链接
                new ArrayList()
        );

    }
}

从配置中我们可以注意到Docket类是主要的，而且在配置中还包含一个groupName()，这是对这个docket备注的名字，也就是说可以创建多个docket指定不同的扫描路径，这也是多人开发时可能会用到，示例如下：

@Bean
public Docket docket1(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}

当然我们也可以将实体类映射出去，只要这个实体在请求接口的返回值上，都能映射到实体项中

最后就是一些常用注释

package com.lxs.swagger.controller;

import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.context.annotation.Configuration;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.PostMapping;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
@Controller

public class SwaggerController {

    @ApiOperation("***的接口")
    @PostMapping("/hello")
    public String Hello(@ApiParam("姓名") String name){
            return null;
    }

}

下面是注释的作用

@ApiOperation(“xxx接口说明”)
@ApiParam(“xxx参数说明”）
@ApiModel(“xxxPOJO说明”)