SpringBoot之----快速了解Swagger集成

最新推荐文章于 2024-01-28 20:28:51 发布

咸鱼_翻身

最新推荐文章于 2024-01-28 20:28:51 发布

阅读量681

点赞数 2

本文链接：https://blog.csdn.net/aaa123_456aaa/article/details/122538303

版权

spring boot 同时被 2 个专栏收录

24 篇文章 1 订阅

订阅专栏

Java

18 篇文章 0 订阅

订阅专栏

Swagger 简介：

Swagger 是一套围绕 Open API 规范构建的开源工具，可以帮助设计，构建，记录和使用 REST API。
Swagger 工具包括的组件：
Swagger Editor ：基于浏览器编辑器，可以在里面编写 Open API规范。类似 Markdown 具有实时预览描述文件的功能。
Swagger UI：将 Open API 规范呈现为交互式 API 文档。用可视化UI 展示描述文件。
Swagger Codegen：将 OpenAPI 规范生成为服务器存根和客户端库。通过 Swagger Codegen 可以将描述文件生成 html 格式和 cwiki 形式的接口文档，同时也可以生成多种言语的客户端和服务端代码。
Swagger Inspector：和 Swagger UI 有点类似，但是可以返回更多信息，也会保存请求的实际参数数据。
Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到 Swagger Hub 中。在 Swagger Hub 中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。
使用 Swagger，就是把相关的信息存储在它定义的描述文件里面（yml 或 json 格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。

1.试运行swagger看看是什么样子

项目结构
在这里插入图片描述

首先我们导入swagger的依赖
pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.5.1</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.wlm</groupId>
    <artifactId>swagger-demo2</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>swagger-demo2</name>
    <description>Demo project for Spring Boot</description>
    <properties>
        <java.version>1.8</java.version>
    </properties>
    <dependencies>

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


        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

HelloController.java

package com.wlm.swagger.controller;

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {
    @RequestMapping("/hello")
    public String hello(){
        return "hello";
    }
}

SwaggerConfig.java

package com.wlm.swagger.config;

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

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

}

运行结果：
在这里插入图片描述

2.接下来我们配置Swagger信息

我们对上面的SwaggerConfig.java进行配置信息
SwaggerConfig.java

package com.wlm.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  //开启Swagger2
public class SwaggerConfig {
    //配置了Swagger的Docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }
    //配置Swagger信息
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("咸鱼_翻身", "https://blog.csdn.net/aaa123_456aaa", "null");
        return new ApiInfo(
                "咸鱼_翻身的 Swagger API Documentation",
                "欢迎关注咸鱼_翻身",
                "1.0",
                "https://blog.csdn.net/aaa123_456aaa",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

运行结果：
在这里插入图片描述

3.配置Swagger扫描接口及配置切换环境

项目结构：
在这里插入图片描述

这是我们实际生产环境
application-pro.properties

server.port=8082

这是我们内部测试环境
application-dev.properties

server.port=8081

这个是切换环境配置
application.properties

spring.profiles.active=dev

HelloController.java

package com.wlm.swagger.controller;

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {
    @RequestMapping("/hello")
    public String hello(){
        return "hello";
    }
}

SwaggerConfig.java

package com.wlm.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  //开启Swagger2
public class SwaggerConfig {
    //配置了Swagger的Docket的bean实例
    @Bean
    public Docket docket(Environment environment){

        //设置要显示的Swagger环境
        Profiles profiles = Profiles.of("dev");
        //获取项目环境：通过environment.acceptsProfiles判断是否处在自己设定的环境中
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)//enable：是否启动Swagger，如果为false，则swagger不能在游览器中访问
                .select()
                //RequestHandlerSelectors：配置要扫描接口的方式
                //basePackage：指定要扫描的包
                //any()：扫描全部
                //none()：不扫描
                //withClassAnnotation: 扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotation: 扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.wlm.swagger.controller"))
                //paths()：过滤什么路径
                .paths(PathSelectors.ant("/hello/**"))
                .build();
    }
    //配置Swagger信息
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("咸鱼_翻身", "https://blog.csdn.net/aaa123_456aaa", "null");
        return new ApiInfo(
                "咸鱼_翻身的 Swagger API Documentation",
                "欢迎关注咸鱼_翻身",
                "1.0",
                "https://blog.csdn.net/aaa123_456aaa",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

运行结果：
我们测试dev环境
在这里插入图片描述
我们再来测试pro环境

4.配置API文档的分组

项目结构：
在这里插入图片描述

通过groupName("")配置多个Docket，(在多人开发中，每个开发者配置一个自己的Swagger，方便管理)。
SwaggerConfig.java

package com.wlm.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 docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("咸鱼_翻身1");
    }
    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("咸鱼_翻身2");
    }
    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("咸鱼_翻身3");
    }

    @Bean
    public Docket docket(Environment environment){
        Profiles profiles = Profiles.of("dev");
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("咸鱼_翻身")
                .enable(flag)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.wlm.swagger.controller"))
                .paths(PathSelectors.ant("/hello/**"))
                .build();
    }
    private ApiInfo apiInfo(){
        Contact contact = new Contact("咸鱼_翻身", "https://blog.csdn.net/aaa123_456aaa", "null");
        return new ApiInfo(
                "咸鱼_翻身的 Swagger API Documentation",
                "欢迎关注咸鱼_翻身",
                "1.0",
                "https://blog.csdn.net/aaa123_456aaa",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

HelloController.java

package com.wlm.swagger.controller;

import com.wlm.swagger.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("/hello")
    public String hello(){
        return "hello";
    }

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

    //Operation接口，不是放在类上，放在方法上面
    @ApiOperation("hello2控制类")
    @GetMapping("/hello2")
    public String hello2(@ApiParam("用户名") String username){
        return "hello2"+username;
    }

    @ApiOperation("post控制类")
    @PostMapping("/postT")
    public User postT(@ApiParam("用户") User user){
        return user;
    }
}

User.java

package com.wlm.swagger.pojo;

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

//@Api(注释)
@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;
}

运行结果：
在这里插入图片描述
我们再来点开下面的models

我们再来点开hello-controller

在这里插入图片描述
最后我们再点开postT

那我们不妨在线测试一下：

5.总结

我们可以通过Swagger给一些比较难理解的属性或接口增加注释信息
接口文档实时更新
可以在线测试
【注意】在正式发布时要关闭Swagger！！！可以保证安全和避免浪费性能

咸鱼_翻身

关注

2
点赞
踩
4

收藏

觉得还不错? 一键收藏
打赏
0
评论
SpringBoot之----快速了解Swagger集成

Swagger 简介：Swagger 是一套围绕 Open API 规范构建的开源工具，可以帮助设计，构建，记录和使用 REST API。Swagger 工具包括的组件：Swagger Editor ：基于浏览器编辑器，可以在里面编写 Open API规范。类似 Markdown 具有实时预览描述文件的功能。Swagger UI：将 Open API 规范呈现为交互式 API 文档。用可视化UI 展示描述文件。Swagger Codegen：将 OpenAPI 规范生成为服务器存根和客户端库。
复制链接

扫一扫