Swagger快速学习

最新推荐文章于 2024-07-22 14:15:06 发布

恋志传奇

最新推荐文章于 2024-07-22 14:15:06 发布

阅读量115

点赞数

分类专栏：后端文章标签： java

本文链接：https://blog.csdn.net/qq_43202405/article/details/117772638

版权

后端专栏收录该内容

21 篇文章 0 订阅

订阅专栏

1、学习目标:

了解Swagger的作用和概念
了解前后端分离
在SpringBoot中集成Swagger

2、Swagger简介

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

Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。

优点：

支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

作用：

最流行的API框架
RestFul Api 文档在线生成工具===Api 文档与API定义同时更新
直接运行可以直接测试API接口
支持多种语言（java,php）

3、springboot集成swagger2

3.1 导入相关的依赖

（搜索网址：https://mvnrepository.com/search?q=Springfox）

<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.2 编写一个hello工程

package com.xuexi.swagger.controller;

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

@RestController
public class HelloController {
    @RequestMapping(value = "/hello")
    public String helloWorld(){

        return "hello";
    }
}

3.3 进行包的配置

由于导入的包属于外部的并不归属于，因此我们一般需要进行配置（在config 包下进行配置）

（配置完成之后运行http://localhost:8080/swagger-ui.html）进行测试

package com.xuexi.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 {

    // 1. 进行配置Swagger 的 Docket的bean
    @Bean
    public  Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());

    }

    //2. 配置Swagger的信息APIINFO
    private ApiInfo apiInfo(){
        // 作者的信息
        Contact DEFAULT_CONTACT = new Contact("hlb", "www.baidu.com", "hlbsunmoon@163.com");
        return new ApiInfo(
                "Swagger测试文档",
                "为了学习",
                "V1.0",
                "urn:tos",
                DEFAULT_CONTACT,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
        }

}

3.4 进一步的配置（接口扫描的配置）

package com.xuexi.swagger.config;

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

    // 1. 进行配置Swagger 的 Docket的bean
    @Bean
    public  Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xuexi.swagger.controller")) // 配置扫描的的controller
//                .paths()   这里是过滤的路径
                .build();

    }

    //2. 配置Swagger的信息APIINFO
    private ApiInfo apiInfo(){
        // 作者的信息
        Contact DEFAULT_CONTACT = new Contact("hlb", "www.baidu.com", "hlbsunmoon@163.com");
        return new ApiInfo(
                "Swagger测试文档",
                "为了学习",
                "V1.0",
                "urn:tos",
                DEFAULT_CONTACT,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
        }

}

3.5 配置文档，API文档的分组

多人协同的开发，每个人创建一个Docket,并进行赋予groupName即可，最终通过bean来进行汇总管理
个人疑问：代码进行版本控制时。每个人的代码配置文件拉取为相同的配置。

3.6 配置文档，API文档的注释

实体类：

package com.xuexi.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.xuexi.swagger.controller;

import com.xuexi.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.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {
    @GetMapping (value = "/hello")
    public String helloWorld(){
        return "hello";
    }

    // 只要我们的接口中存在相应的类，则swagger将会扫描到
    @ApiOperation("用户控制类")
    @PostMapping(value = "/user")
    public User user(@ApiParam("用户名参数") String name){
        return new User();
    }
}

说明：该博客为观看相应视频所做笔记，进行学习