SpringBoot-Swagger

时间 2020-10-13

标签 html java web spring apache 编程 api 浏览器安全 springboot 栏目 Spring 繁體版

原文原文链接

Swagger

Swagger

1. 简介

号称世界上最流行的API框架
RestFul API 文档在线自动生成工具 => API文档与API定义同步更新
直接运行, 能够在线测试API接口
支持多种语言
在项目中使用Swagger须要SpringFox
- Swagger2
- ui

2. SpringBoot集成Swagger

1. 导入依赖

Swagger3.0直接导入Springfox Boot Starter就能够了html

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

2.X版本须要导入Swagger2.0和UIjava

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

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

咱们这里仍是使用2.X版本web

2. 配置Swagger

package com.wang.config;

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

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

注意spring

只要在Swagger配置类上加上@EnableSwagger2注解, 就可使用Swagger2了
Swagger的地址为http://localhost:8080/swagger-ui.html

3. Swagger配置

1. 配置Swagger信息

Swagger的Bean实例 ==> Docketapache

package com.wang.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.service.VendorExtension;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

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

    //配置了Swagger的Docket的Bean实例
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    //配置Swagger信息 apiInfo
    private ApiInfo apiInfo() {
        //做者信息
        Contact contact = new Contact("wang", "https://www.cnblogs.com/wang-sky/", "715180879@qq.com");

        return new ApiInfo(
                "个人Swagger接口文档",
                "这是一个Swagger接口文档",
                "V 1.0",
                "https://www.cnblogs.com/wang-sky/",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<VendorExtension>());
    }


}

这里修改的是Swagger页面的一些信息, 结果以下编程

注意api

Docket不要忘了注册Bean并返回一个new Docket
返回的Docket要传入一个参数指定产生的文档的类型, 咱们这里使用 DocumentationType.SWAGGER_2

2. Swagger配置扫描接口

Docket.select()浏览器

@Bean
public Docket docket() {
    //RequestHandlerSelectors 配置要扫描接口的方式
    /*
    basePackage     指定要扫描的包
    any             扫描所有
    none            都不扫描
    withClassAnnotation 扫描类上的注解,参数是一个注解的反射对象, 好比 withClassAnnotation(RestController.class)
    withMethodAnnotation    扫描方法上的注解
     */
    //paths 过滤的路径, 须要传入PathSelectors.xxx 选择过滤的方式
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.wang.controller"))
            .paths(PathSelectors.ant("/wang/**"))
            .build();
}

注意安全

apis 扫描, 要传入RequestHandlerSelectors.xxx 指定扫描的方式
- basePackage 指定要扫描的包
- any 扫描所有
- none 都不扫描
- withClassAnnotation 扫描类上的注解,参数是一个注解的反射对象, 好比 withClassAnnotation(RestController.class)
- withMethodAnnotation 扫描方法上的注解
paths 过滤的路径, 须要传入PathSelectors.xxx 选择过滤的方式
最后要.build(), 建造者模式, 同时因为这是链式编程, 必定要写!
select().XXX.XXX...bulid()是一套, 中间能够写的方法是肯定的, 不能乱写

3. 配置Swagger是否启动

只在生产环境下使用Swagger, 而在发布的时候不使用的方法springboot

分别创建不一样环境的yml

在application中选择启动的环境, 这里选择生产环境

spring:
  profiles:
    active: dev

配置Swagger

//配置了Swagger的Docket的Bean实例
@Bean
public Docket docket(Environment environment) {
    //RequestHandlerSelectors 配置要扫描接口的方式
    /*
    basePackage     指定要扫描的包
    any             扫描所有
    none            都不扫描
    withClassAnnotation 扫描类上的注解,参数是一个注解的反射对象, 好比 withClassAnnotation(RestController.class)
    withMethodAnnotation    扫描方法上的注解
     */
    //paths 过滤的路径, 须要传入PathSelectors.xxx 选择过滤的方式

    //设置要显示的Swagger环境
    Profiles profiles = Profiles.of("dev");

    //经过environment.acceptsProfiles, 判断是否处在本身设定的环境当中
    boolean flag = environment.acceptsProfiles(profiles);

    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.wang.controller"))
            .paths(PathSelectors.ant("/wang/**"))
            .build()
            .enable(flag);
}

注意

.enable
只能在select().XXX.XXX....bulid() 外面写
默认为true, 若是为False, 则Swagger不能在浏览器中访问
要用 Profiles profiles = Profiles.of("dev"); 指定激活的环境的名字
得到当前的生产环境(application指定的环境), 要给Docket传入一个Environment对象, 其中保存了当前环境的名字
environment.acceptsProfiles(profiles); 利用此方法得到是否在给定环境的布尔值

4. 配置API文档的分组

.groupName("个人API")

配置多个分组, 只须要配置多个Docket便可

4. 实体类配置

1. 实体类的注解

package com.wang.pojo;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
//@Api("注释")
@ApiModel("用户实体类")
public class User {

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

@ApiModel或者@Api在类上

@ApiModelProperty在属性上

属性为私有, 要写getter才能取到属性名

结果显示在Model上

2. 接口类的注解

package com.wang.controller;

import com.wang.pojo.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @GetMapping(value = "/hello")
    public String hello() {
        return "Hello!";
    }

    //只要咱们的接口中, 返回值中存在实体类, 他就会被扫描到Swagger中
    @PostMapping("/user")
    public User user() {
        return new User();
    }

    //Operation接口
    //Get请求中, 若是添加了字段的注释@ApiParam, Swagger没法测试
    @ApiOperation("Hello2接口")
    @GetMapping("/hello2")
    public String hello2(String username) {
        return "hello " + username;
    }

    //Operation接口
    @ApiOperation("Hello3接口")
    @PostMapping("/hello3")
    public User hello3(@ApiParam("用户") User user) {
        return user;
    }
}

注意

只要咱们的接口中, 返回值中存在实体类或者字符串, 他就会被扫描到Swagger中
@ApiOperation 方法的注释
@ApiParm 参数的注释
Get请求中, 若是添加了字段的注释@ApiParam, Swagger没法测试

5. 总结

咱们能够经过Swagger给一些比较难理解的属性或者接口, 增长注释信息
接口文档实时更新
能够在线测试
注意, 在正式发布的时候, 关闭Swagger(出于安全考虑, 并且节省运行内存)