swagger接口文档使用

swagger接口文档

一，swagger简介

前后端分离

vue + springboot 一套解决方案

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

前后端分离时代：

后端：后端控制层，服务层，数据访问层【后端团队】
前端：前端控制层（双向绑定），视图层【前端团队】
- 伪造后端数据，json。已经存在，无需后端，全段工程依旧能够跑起来。
前后端如何交互？===> API json
前后端相对独立，松耦合
前后端可用部署在不同的服务器上

前后端分离产生，一个问题

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

解决方法：

指定schema 【计划的提纲】。实时更新最新api，降低集成的风险；
早些年：制定word计划文档；
前后端分离：
- 前端测试后端接口：postman
- 后端提供接口，需要实时更新最新的消息及改动！

swagger 诞生

号称世界上最流行的api框架
restful api文档在线自动生成工具=> api 文档与api定义同步更更新
直接运行，在线测试api接口
支持多种语言 java,php,py…

官网：https://swagger.io

在项目中使用swagger springbox

swagger2
ui

二，springboot集成swagger

依赖

导入相关依赖
- springfox-swagger2
- springfox-swagger-ui

pom

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

编写helloworld接口

package cn.bitqian.swagger.controller;

import org.springframework.web.bind.annotation.*;

/**
 * hello world
 * @author echo lovely
 * @date 2020/10/28 19:23
 */
@RestController
public class HelloController {
    
    

    @RequestMapping(value = "/hello")
    public String hello() {
    
    

        return "hello";
    }

}

配置swagger ==> config 配置类

开启swagger，Enablexxx

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

测试运行

http://localhost:8080/swagger-ui.html

三，配置swagger

来告诉交接人员，接口是干嘛的，对controller的接口进行描述。也可以设置接口访问权限。

package cn.bitqian.swagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;

/**
 * swagger配置类
 * @author echo lovely
 * @date 2020/10/28 19:35
 */
@Configuration
@EnableSwagger2 // 开启swagger2
public class SwaggerConfig {
    
    

	// 文档的标题，和描述！作者的信息deng..
    @Bean
    public Docket docket() {
    
    

        return new Docket(DocumentationType.SWAGGER_2).apiInfo(appInfo());
    }

    // api 信息 接口文档的头部信息描述
    public ApiInfo appInfo() {
    
    

        Contact contact = new Contact("bitqian", "http://example.com", "[email protected]");

        return new ApiInfo("bitqian的swagger文档",
                "用来描述此接口的功能，内容。",
                "v1.0",
                "http://example.cn", contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

}

swagger 配置扫描接口


   @Bean
    public Docket docket() {
    
    

        return new Docket(DocumentationType.SWAGGER_2).apiInfo(appInfo()).
                select().
                // RequestHandlerSelectors 配置要扫描的接口的方式
                // basePackage 指定要扫描的包
                // any() 扫描全部
                // none() 不扫描
                // withClassAnnotation(Controller.class)  扫描类上的注解, 生效
                // withMethodAnnotation(RequestMapping.class)  扫描方法上的注解, 生效
                apis(RequestHandlerSelectors.basePackage("cn.bitqian.swagger.controller")).
                // paths(PathSelectors.ant("/bitqian/**"))  扫描指定的接口
            	// PathSelectors.regex("")
                paths(PathSelectors.ant("/hello/**"))
                .build();
    }

如何做到只在生产环境中启动swagger？

判断是否是生产环境
注入enable

    @Bean
    public Docket docket(Environment environment) {
    
    

        // 获取当前环境 是生产环境 启动swagger
        boolean isProFlag = environment.acceptsProfiles(Profiles.of("pro"));

        System.out.println("is dev environment....===========>" + isProFlag);

        return new Docket(DocumentationType.SWAGGER_2).apiInfo(appInfo()).groupName("bitqian").
                enable(isProFlag). // 是否启动swagger 如果为false，则不能在浏览器中使用swagger
                select().
                apis(RequestHandlerSelectors.basePackage("cn.bitqian.swagger.controller")).
                // paths(PathSelectors.ant("/hello/**")).
                build();
    }

配置api文档的分组

整出多个docket，多个人写不同的接口

@Bean
public Docket docket1() {
    
    

    return new Docket(DocumentationType.SWAGGER_2).groupName("bitqian666 group1");
} 

@Bean
public Docket docket12() {
    
    

    return new Docket(DocumentationType.SWAGGER_2).groupName("bitqian666 group2");
}

四，swagger注解用于对实体类，接口的描述

pojo

package cn.bitqian.swagger.entity;

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

/**
 * 给实体类生成文档
 * @author echo lovely
 * @date 2020/10/29 21:09
 */
@ApiModel("user实体类")
public class User {
    
    

    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;

    public User() {
    
    }

    public User(String username, String password) {
    
    
        this.username = username;
        this.password = password;
    }
}

controller

package cn.bitqian.swagger.controller;

import cn.bitqian.swagger.entity.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;

/**
 * hello world
 * @author echo lovely
 * @date 2020/10/28 19:23
 */
@RestController
public class HelloController {
    
    

    @ApiOperation("get/post都可的hello接口")
    @RequestMapping(value = "/hello")
    public String hello() {
    
    

        return "hello";
    }

    @ApiOperation("get的hello接口, 返回一个空 user")
    @GetMapping(value = "/hello1")
    public User hello1() {
    
    

        return new User();
    }

    @ApiOperation("hello1 接口post way~")
    @PostMapping(value = "/hello1")
    public User hello1(@ApiParam("传递用户") User user) {
    
    

        return user;
    }

    @ApiOperation("登录接口 post way~")
    @PostMapping(value = "/login")
    public String login(@ApiParam("登录用户名") @RequestParam("username") String username,
                        @ApiParam("登录密码")  @RequestParam("password") String password) {
    
    

        return "ok" + "{" + username + ", " + password + "}";
    }


}

五，你以为的是swagger只能提供接口描述信息？呵~

swagger能测试呀

try it out

六，最后

我们可用通过swagger给一些比较难理解的属性或者接口，增加注释信息
接口文档实时更新
可以在线测试

swagger是一个优秀的工具，几乎所有大公司都有使用它，更符合迭代开发的需求。

【注意点】在正式发布的时候，关闭swagger！！！处于安全考虑。而且节省运行的内存。