Swagger初学

253 阅读2分钟

Swagger介绍及使用

官网链接:swagger.io/

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码,允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单。

1.作用

同步更新API文档和API

建立了Spring-swagger项目,后面改成了现在的Springfox。通过在项目中引入Springfox,可以扫描相关的代码,生成该描述文件,进而生成与代码一致的接口文档和客户端代码。这种通过代码生成接口文档的形式,在后面需求持续迭代的项目中,显得尤为重要和高效。

2.SpringBoot中集成Swagger

创建项目

导入相关依赖

<!-- 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.配置wagger

package com.gip.swagger.config;

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

@Configuration
@EnableSwagger2
public class SwaggerConfig {
}

package com.gip.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;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact=new Contact(
                "Gip",
                "",
                "798484107@qq.com"
        );
        return new ApiInfo("Gip的API",
                "描述下这玩意",
                "1.0",
                "urn:tos",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

image-20210522190046049

4.判断项目环境

创建多个配置文件

image-20210522195518353

激活生产的

# 激活配置文件
spring.profiles.active=dev
package com.gip.swagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.PathSelectors;
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
public class SwaggerConfig {
    @Bean
    public Docket docket(Environment environment) {
        Profiles profiles=Profiles.of("dev");

        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .enable(flag)
                .select()
                //any()
                //basePackage("com.gip.swagger.controller")
                //none()
//                .apis(RequestHandlerSelectors.any())
//                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact=new Contact(
                "Gip",
                "",
                "798484107@qq.com"
        );
        return new ApiInfo("Gip的API",
                "描述下这玩意",
                "1.0",
                "urn:tos",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

image-20210522195507588

image-20210522195640560

系统环境变量,

设置你要激活的环境,调用acc...方法返回布尔值,在设置下

image-20210522195742225

4.分组

.groupName("A俊")

image-20210522201004148

配置多个分组,容器中注入添加多个Docket对象

    @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");
    }

image-20210522201443404

5.注释信息

package com.gip.swagger.pojo;

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

@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;
}
package com.gip.swagger.controller;

import com.gip.swagger.pojo.User;
import io.swagger.annotations.Api;
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.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Api(tags = "用户相关")
public class HelloController {
    @RequestMapping("/hello")
    public String Hello(){
        return "hello";
    }
    @PostMapping("/")
    public User  user(){
        return new User();
    }
    @GetMapping("/hello2")
    @ApiOperation("hello控制方法")
    public String Hello2(@ApiParam("参数用户名") String username){
        return "hello";
    }
}

image-20210522204034974

image-20210522204057072

总结:

  1. 可以给接口,或者方法,属性打上注释,方便他人理解
  2. 接口文档实时更新
  3. 可以在线测试

注意:在正式发布时候,关闭Swagger!,安全问题,也可以提升性能!