Swagger--世界上最流行的API框架

Swagger–世界上最流行的API框架

一：关于Swagger

前后端分离

Vue+Springboot

后端时代：前段只用管理静态页面；html==>后端，模板引擎jsp=>后端是主力

前后端分离时代：

后端：后端控制层，服务处，数据访问层

前段：前段控制层，视图层

前后端如何交互？==》API

前后端相对独立，松耦合

前后端甚至可以部署在不同的服务器上；

产生一个问题：

前后端集成联调，前后端人员无法做到，即使协调，尽早解决，最终导致问题集中爆发。

解决方案：

首先指定schema[计划的提纲]，实时更新最新的API，降低集成风险；

早些年：指定word计划文档；

前后端分离：

前段测试后端接口：postman

后端提供接口，需要实时更新最新的消息以及改动

swagger号称世界上最流行的API框架

RestFul API 文档在线自动生成工具 =》Api文档与Api定义同步更新

直接运行可以在线直接测试API接口

支持多种语言

二：在项目中使用Swagger

springboot集成swagger

1.新建一个springboot–web项目

2.添加Swagger的maven依赖

 <!-- 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>

3.在config包中新建一个SwaggerConfig的类

@Configuration
@EnableSwagger2
@ConditionalOnExpression("${swagger.enable}") //开启访问接口文档的权限
public class SwaggerConfig {

    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("开发人员A");
    }

    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("开发人员B");
    }

    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("开发人员C");
    }

    @Bean
    public Docket userRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("华仔")  //模块名称
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.mongoweb.mongoweb.controller"))  //扫描的控制器路径
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("xxx项目开发接口文档")    //接口文档标题
                .description("此文档仅供开发技术组领导、开发人员使用")   //描述
                .termsOfServiceUrl("http://www.xxx.com/")   //相关的网址
                .contact(new Contact("后端开发","http://www.xxx.com/","8xxxxx67@qq.com"))    //作者  邮箱等
                .version("1.0")  //版本号
                .build();
    }
}

4.Swagger接口配置文档

在application.properties中加上：

swagger.enable=true

5.controller层中注解使用

@Controller
@RequestMapping("/app")
@Api(tags = "用户登陆相关Api")
public class UserController {
    @PostMapping(value = "/user")
    public  User user(){
        return new User();
    }

    @ApiOperation("Post测试类")
    @PostMapping(value = "/postt")
    public  User postt(@ApiParam("用户名") User user){
        return user;
    }

    @ApiOperation("hell的Api")
    @GetMapping(value = "/hello2")
    public String hello(@ApiParam("用户名") String username){
        return "hello"+username;
    }
}
//在controller层加上@Api注解，tags是对控制器命名，description可以对该控制器进行描述

6.浏览器输入网址http://localhost:8080/swagger-ui.html

三：Swagger使用的注解及其说明

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

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

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

@ApiImplicitParam：用来注解来给方法入参增加说明。
参数说明:
paramType：指定参数放在哪个地方

   header：请求参数放置于Request Header，使用@RequestHeader获取

   query：请求参数放置于请求地址，使用@RequestParam获取

   path：（用于restful接口）-->请求参数的获取：@PathVariable

   body：（不常用）请求体

   form（不常用）表单

name：参数名

dataType：参数类型

required：参数是否必须传

true | false

value：说明参数的意思

defaultValue：参数的默认值

@ApiResponses：用于表示一组响应

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

  code：数字，例如400
  message：信息，例如"请求参数没填好"
  response：抛出异常的类   

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

@ApiModelProperty：描述一个model的属性

四：SpringBoot中集成了swagger后无法访问http://localhost:8080/swagger-ui.html

没有配置资源路径，在webConfig中加上：

@Configuration
public class WebMvcConfig extends WebMvcConfigurerAdapter {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {

        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/templates/**")
                .addResourceLocations("classpath:/META-INF/resources/templates/");
    }
}

五：实现测试环境开启Swagger，发行环境关闭Swagger