Swagger

程序员文章站 2022-07-02 15:04:17

...

Swagger

导语：

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码，等等等的问题。

为了解决以上API接口问题，就出现了Swagger！说白了就是为了解决前后端分离开发带来的对接问题

Swagger是什么？

Swagger是一款让你更好地书写API文档的框架。

Swagger是一个功能强大且易于使用的API开发人员工具套件，适用于团队和个人，可在整个API生命周期（从设计和文档到测试和部署）中进行开发。

Swagger怎么用？

本文使用的是Springboot构建项目！项目使用Swagger2！

Swagger需要的组件

Swagger需要使用到Springfox

Swagger2
ui

先看看Swagger-ui界面

Swagger

创建springboot项目

创建的是web项目，这里不讲如何创建。

到Maven查找组件

Maven官网

Swagger

把依赖导入pom文件

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

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-tomcat</artifactId>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
        <exclusions>
            <exclusion>
                <groupId>org.junit.vintage</groupId>
                <artifactId>junit-vintage-engine</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>
</dependencies>

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

编写一个HelloController工程

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

@RestController
public class HelloController {

    @RequestMapping("/hello.do")
    public String hello(){
        return "hello swagger";
    }
}

启动Springboot，访问controller，没有出错就继续往下走。

编写Swagger配置类

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

@Configuration  // 定义为配置类
@EnableSwagger2 // 开启Swagger2
public class SwaggerConfig {
}

访问

看看我们导入的依赖，可以找到一个swagger-ui.html页面

Swagger

访问http://localhost:8080/swagger-ui.html

Swagger

第一个简单的swagger页面就弄好了！

配置Swagger

Swagger的bean实例 Docket

@Configuration  // 定义为配置类
@EnableSwagger2 // 开启Swagger2
public class SwaggerConfig {

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

点进Docket构造器里面，ApiInfo使用默认的配置，此时我们可以为ApiInfo设值

public Docket(DocumentationType documentationType) {
    this.apiInfo = ApiInfo.DEFAULT;	//api信息
    this.groupName = "default";
    this.enabled = true;
    this.genericsNamingStrategy = new DefaultGenericTypeNamingStrategy();
    this.applyDefaultResponseMessages = true;
    this.host = "";
    this.pathMapping = Optional.absent();
    this.apiSelector = ApiSelector.DEFAULT;
    this.enableUrlTemplating = false;
    this.vendorExtensions = Lists.newArrayList();
    this.documentationType = documentationType;
}

点进ApiInfo类中，查看默认配置DEFAULT

static {
    DEFAULT = new ApiInfo("Api Documentation", "Api Documentation", "1.0", "urn:tos", DEFAULT_CONTACT, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
}

自定义ApiInfo信息

@Configuration  // 定义为配置类
@EnableSwagger2 // 开启Swagger2
public class SwaggerConfig {

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

    // 配置swagger的ApiInfo信息
    public ApiInfo apiInfo() {

        // 作者信息
        Contact contact = new Contact("hao","https://blog.csdn.net/weixin_44151739/article/details/109183587","aaa@qq.com");

        return new ApiInfo(
                "hao的Swagger API文档",
                "今天怎么过，明天就怎么过！",
                "V1.0",
                "https://blog.csdn.net/weixin_44151739/article/details/109183587",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

启动服务器访问

Swagger

配置扫描接口及配置

Swagger

默认的不管，我们看自定义的controller，存在多种方式访问，因为我们代码中使用的是@RequestMapping("/hello.do")，没有设置具体访问方式

接下来我们讲Swagger如何扫描到我们controller的

Docket的select()方法

指定扫描包

// 配置Swagger的Docket的bean实例
@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .select()
        // RequestHandlerSelectors 配置要扫描接口的方式
        // basePackage 指定要扫描的包
        .apis(RequestHandlerSelectors.basePackage("com.hao.swagger.controller"))
        .build();
}

重启服务器，访问，你会发现默认的那个不见了，只剩下我们指定包中的controller

Swagger

点进RequestHandlerSelectors类中，具体内容省略，查看一下扫描方法

public class RequestHandlerSelectors {
    // 扫描所有
    public static Predicate<RequestHandler> any() {
    }

    // 不扫描
    public static Predicate<RequestHandler> none() {
    }

    // 通过方法的注解去扫描
    public static Predicate<RequestHandler> withMethodAnnotation(final Class<? extends Annotation> annotation) {
    }

    // 通过类的注解去扫描
    public static Predicate<RequestHandler> withClassAnnotation(final Class<? extends Annotation> annotation) {
    }

    private static Function<Class<?>, Boolean> annotationPresent(final Class<? extends Annotation> annotation) {
    }

    private static Function<Class<?>, Boolean> handlerPackage(final String basePackage) {
    }

    // 扫描指定包
    public static Predicate<RequestHandler> basePackage(final String basePackage) {
    }

    private static Optional<? extends Class<?>> declaringClass(RequestHandler input) {
    }
}

过滤指定路径

// 配置Swagger的Docket的bean实例
@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            // RequestHandlerSelectors 配置要扫描接口的方式
            // basePackage 指定要扫描的包
            .apis(RequestHandlerSelectors.basePackage("com.hao.swagger.controller"))
            // paths 过滤路径
            // ant 过滤指定名称
            .paths(PathSelectors.ant("/hao/**"))
            .build();
}

重启服务器，访问，没有接口了，我们自定义就一个接口，路径为/hello.do，此时要扫描的是/hao开头的

Swagger

点进PathSelectors类中，具体内容省略，查看一下过滤方法

public class PathSelectors {
    // 过滤全部
    public static Predicate<String> any() {
    }

    // 不过滤
    public static Predicate<String> none() {
    }

    // 正则
    public static Predicate<String> regex(final String pathRegex) {
    }

    // 指定过滤
    public static Predicate<String> ant(final String antPattern) {
    }
}

配置是否启动Swagger

// 配置Swagger的Docket的bean实例
@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            // 是否开启Swagger,默认为true（开启），现在设置为false
            .enable(false)
            .select()
            // RequestHandlerSelectors 配置要扫描接口的方式
            // basePackage 指定要扫描的包
            .apis(RequestHandlerSelectors.basePackage("com.hao.swagger.controller"))
            // paths 过滤路径
            // ant 过滤指定名称
            .paths(PathSelectors.ant("/hao/**"))
            .build();
}

重启服务器，访问，Swagger被禁用

Swagger

Swagger

Swagger

Swagger是什么？

Swagger怎么用？

配置Swagger

配置扫描接口及配置

Springboot中集成Swagger2框架的方法

在Spring Boot中使用swagger-bootstrap-ui的方法

SpringBoot结合Swagger2自动生成api文档的方法

详解SpringBoot结合swagger2快速生成简单的接口文档

四步五分钟Spring4快速集成Swagger

SpringBoot集成swagger的实例代码

Spring MVC+FastJson+Swagger集成的完整实例教程

django-rest-swagger对API接口注释的方法

python-tornado的接口用swagger进行包装的实例

SpringBoot集成Swagger2实现Restful(类型转换错误解决办法)