【WEEK14】【DAY3】Swagger第一部分【中文版】

news2024/11/18 16:31:03

2024.5.29 Wednesday

16.Swagger
- 16.1.Swagger简介
- - 16.1.1.前后端分离
  - 16.1.2.前后端分离时代
  - 16.1.3.产生的问题
  - 16.1.4.解决方案
  - 16.1.5.Swagger
- 16.2.SpringBoot集成Swagger
- - 16.2.1.新建swagger-demo项目
  - 16.2.2.导入依赖
  - - 16.2.2.1.springfox-swagger2
    - 16.2.2.2.springfox-swagger-ui
    - 16.2.2.3.pom.xml
  - 16.2.3.新建controller文件夹
  - - 16.2.3.1.新建HelloController.java
    - 16.2.3.2.运行SwaggerDemoApplication.java
  - 16.2.4.配置Swagger
  - - 16.2.4.1.新建config文件夹，SwaggerConfig.java
    - 16.2.4.2.解决http://localhost:8080/swagger-ui.html打不开的方法
    - 16.2.4.3.重新运行SwaggerDemoApplication.java
- 16.3.配置Swagger
- - 16.3.1.修改SwaggerConfig.java
  - 16.3.2.重启

16.Swagger

学习目标

了解Swagger的概念及作用
了解前后端分离
在springboot中集成swagger自动生成API文档

16.1.Swagger简介

16.1.1.前后端分离

主流方案：Vue+SpringBoot
后端时代：前端只用管理静态页面；html==>后端。模板引擎JSP=>后端才是主力

16.1.2.前后端分离时代

前端 -> 前端控制层（双向绑定）、视图层
- 使用json伪造后端数据。指不需要后端，前端工程依然能够运行
后端 -> 后端控制层、服务层、数据访问层
前后端通过API进行交互
前后端相对独立且松耦合，甚至可以部署在不同的服务器上

16.1.3.产生的问题

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

16.1.4.解决方案

首先定义schema [ 计划的提纲 ]，并实时跟踪最新的API，降低集成风险；
早些年：指定word计划文档；
前后端分离：
- 前端测试后端接口：postman
- 后端提供接口，需要实时更新最新的消息及改动

16.1.5.Swagger

号称世界上最流行的API框架
Restful Api 文档在线自动生成器 => API 文档与API 定义同步更新
直接运行，在线测试API
支持多种语言（如：Java，PHP等）
官网：https://swagger.io/

16.2.SpringBoot集成Swagger

SpringBoot集成Swagger => springfox，两个jar包
Springfox-swagger2
springfox-swagger-ui
使用swagger2：jdk版本应为1.8+

16.2.1.新建swagger-demo项目

在这里插入图片描述

添加maven支持（在Project Structure->Modules点击加号添加对应项目），
在这里插入图片描述

按照惯例修改settings中的maven，jdk和Java版本，Project Structure中的jdk和Java版本。修改pom中的springframework版本到2.7.13，修改pom.xml添加Thymeleaf依赖，重新加载Maven。
删除多余文件
在这里插入图片描述

16.2.2.导入依赖

在这里插入图片描述

16.2.2.1.springfox-swagger2

Maven Repository: io.springfox » springfox-swagger2 » 2.9.2 (mvnrepository.com)

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

16.2.2.2.springfox-swagger-ui

Maven Repository: io.springfox » springfox-swagger-ui » 2.9.2 (mvnrepository.com)

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

16.2.2.3.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.7.13</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.example</groupId>
    <artifactId>swagger-demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>swagger-demo</name>
    <description>swagger-demo</description>
    <properties>
        <java.version>8</java.version>
    </properties>
    <dependencies>

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

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

16.2.3.新建controller文件夹

16.2.3.1.新建HelloController.java

在这里插入图片描述

package com.P47.controller;

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

@RestController
public class HelloController {

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

16.2.3.2.运行SwaggerDemoApplication.java

默认的url：/error
测试HelloController：http://localhost:8080/hello
在这里插入图片描述

16.2.4.配置Swagger

16.2.4.1.新建config文件夹，SwaggerConfig.java

在这里插入图片描述

package com.P47.config;

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

@Configuration  //等价于@Component
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
}

16.2.4.2.解决http://localhost:8080/swagger-ui.html打不开的方法

见博客https://blog.csdn.net/2401_83329143/article/details/138858363
修改application.properties

spring.application.name=swagger-demo
spring.mvc.pathmatch.matching-strategy=ant_path_matcher

16.2.4.3.重新运行SwaggerDemoApplication.java

http://localhost:8080/swagger-ui.html
在这里插入图片描述

16.3.配置Swagger

Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger

16.3.1.修改SwaggerConfig.java

package com.P47.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  //等价于@Component
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
    //配置了Swagger的bean实例Docket，以配置Swagger的具体参数
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)  //源码见DocumentationType.classpublic class DocumentationType extends SimplePluginMetadata方法，选择符合当前版本的进行编辑
                .apiInfo(apiInfo()); //public Docket(DocumentationType documentationType)方法点开ApiInfo进入ApiInfo.class
        //点击进入Docket.class可见各类方法源码
    }

    //配置Swagger信息（apiInfo）
    private ApiInfo apiInfo(){

        //防止DEFAULT_CONTACT(名字改成了contact)报错
        Contact contact = new Contact("联系人名字", "联系人访问链接", "联系人邮箱");

        return new ApiInfo("Swagger Api Documentation", //标题
                "Api Documentation 描述", //描述
                "version 1.0",  //版本号
                "http://terms.service.url",  //组织链接
                contact,    //联系人信息
                "Apache 2.0",   //许可
                "http://www.apache.org/licenses/LICENSE-2.0",   //许可链接
                new ArrayList<>() //扩展
        );
    }
}

16.3.2.重启

http://localhost:8080/swagger-ui.html#/
在这里插入图片描述

这个页面的源码在：D:\apache-maven-3.5.4\repository\io\springfox\springfox-swagger-ui\2.9.2\springfox-swagger-ui-2.9.2.jar!\META-INF\resources\swagger-ui.html