API框架:swagger

Swagger

学习目标

1.了解Swagger的作用和概念
2.了解前后端分离
3.在Spring中集成Swagger

Swagger简介

前后端分离

Vue + SpringBOot
后端时代: 前端只用管理静态页面;html==>后端. 模板引擎 jsp=>后端是主力

前后端分离时代

后端: 后端控制层 服务层 数据访问层
前端: 前端控制层 视图层
无需后端可以单独运行
前后端如何交互 API
前后端相对独立,松耦合
前后端甚至可以部署在不同的服务器上

问题
前后端集成联调,前后端人需"及时协商"
解决方案
首先是定 schema[计划的提纲],实时更新API,降低集成的风险
早些年: 指定word计划文档
前后端分离:
前端测试后端接口:postman
后端提供接口,需要实更新最新的消息及改动
Swagger API
号称世界最流行的Api框架
RestFul Api 文档在线自动生成工具 api 文档已api定义同步更新
直接运行,可以在线测试api接口;
支持多种语言
官网文档 : https://swagger.io/docs/open-source-tools/swagger-editor/

项目使用 需要 springbox;

sewagger2
ui

SpringBoot 集成Swaggr

1.创建 SpringBoot 项目

2.导入maven依赖

<!--Swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

3.编写 helloController

import com.sl.swagger.pojo.User;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloMyContreoller {

    @GetMapping("/hello")
    public String hello(){
        return "hello";
    }

    @PostMapping("/hello")
    public User user(){
        return new User();
    }
}

4.编写config

@Configuration                 //申明这个是一个组件注册倒spring当中
@EnableSwagger2                //开启Swagger2
public class SwaggerConfig {
 //配置了Swagger的 Docket 的bean实例
    @Bean
    public Docket docket(Environment environment){
        Profiles profiles = Profiles.of("dev","test");
        //获取项目环境environment 判断是否处在自己设置的 环境当中
        // 如果检测到该环境 b = true 则开启 Swagger服务
        boolean b = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("佘莉") 
                //enable()参数boolean false未启动 无法访问Swagger true 启动
                .enable(b)
                .select()
                //RequestHandlerSelectors 配置要扫描接口的方式
                // basePackage() 指定要扫描的包 参数 包路径
                //any() 扫描全部
                //none() 不扫描
                //withclassAnnotation() 扫描类上的注解,参数为 一个注解的反射对象 RestController
                //withMethodAnnotation() 扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("con.sl.swagger.controller"))
                //过滤
                //ant() 选择过滤的路径 参数 
                .paths(PathSelectors.ant("/sl/**"))
                .build();  //build 工厂模式
    }


    //配置Swagger 信息 = apiInfo
    //自定 apiinfo
    private ApiInfo apiInfo(){
        Contact contact = new Contact("佘莉", "https://mp.csdn.net/console/article", "1125400943@qq.com");
        return new ApiInfo("佘莉的Swagger API文档"
                , "孤鸿寄语莫苍离"
                , "v1.0"
                , "https://mp.csdn.net/console/article"
                , contact
                , "Apache 2.0"
                , "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
    }
}

.groupName("佘芳")  //定义分组的名字
可以创建多个 分组   Docket 实例即可
 @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("佘芳");
    }

5.实体类 扫描

只要我们的接口中返回了实体类那么 他就会别扫描到Swagger

@PostMapping("/hello")
    public User user(){
        return new User();
    }

可以为实体类注释 @ApiModel(“用户类”)

package com.sl.swagger.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("用户类")
public class User {
    @ApiModelProperty("用户名")
    public String name;
    @ApiModelProperty("用户密码")
    public String pwd;
}

6.接口添加注释

    //可以为该方法添加一个注释
    @ApiOperation("用户")
    @PostMapping("/user")
    public User user(){
        return new User();
    }

注解

@Api(description = "地图接口") 标注控制类
@ApiModel("地区负责人") 标注实体
@ApiOperation("查询所有的地区") 标注方法

7.访问swagger

127.0.0.1:8080/swagger-ui.html

总结

1. 我们可以通过Swagger 给一些比较难以理解的 属性或者接口,增加注释信息
2. 接口文档实时更新
3. 可以在线测试
   Swagger 是一个优秀的 API框架 (工具),大公司基本在用;
   正式发布时,关闭Swagger,为了安全和节省空间