上一节简单介绍了一下Swagger的常用注解,但是如果你还不了解Swagger,我相信你此时肯定还是晕晕乎乎的。不过只要你把这个系列的教程看完,如果还不会用Swagger,尽管来找我。

一、Swagger,启动!

这里我只介绍在Spring中如何使用Swagger,不管你是用的SpringMVC还是SpringBoot,都是可以继续看下去的。

一般我们使用Spring,有两种配置方式,一种基于XML,一种继续Java类。这里我只演示如何使用Java类来配置Swagger,如果你的项目现在是使用的XML配置,也没关系。因为XML和Java类配置是可以混用的嘛。

我的环境是

  • InteliJ IDEA 2018.3
  • springfox-swagger2:2.9.2.

1、引入jar包

我们使用Maven引入jar包,你可能会疑惑为什么swagger前面有个springfox。我在百度上查到的资料是这样的:swagger生成Api文档的原理是生成了一些数据,而swagger原生的解决方案是用yaml格式来保存这些数据,yaml这东西我估计你可能都没听过,所以这种格式其实是不常用的。而在web应用中比较常用的数据传输格式是什么呢?json?对,就是json,springfox-swagger就是用json来传输api数据(swagger原生就是支持json这种格式的,只是没有实现而已),springfox-swagger对springmvc有了良好的支持,所以我们一般都是使用springfox-swagger而不是原生swagger。

说完了swagger,你可能还会有一个疑问,第二个依赖swagger-ui又是个什么鬼?上面说了,swagger生成的是一些数据,springfox-swagger生成的是json数据,但是让你直接去看json数据,我估计你看起来也是头皮发麻。所以就有了swagger-ui这种东西。它的作用主要就是渲染json数据,用一个网页来呈现这些json数据,让我们能更加直观的看到我们的接口文档

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

2、创建一个Swagger配置类

加入了依赖之后,我们就可以开始配置了

package com.juzi.config;

import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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;

/**
 * @author Juzi
 * @date 2018/12/27 12:15
 * Blog https://juzibiji.top
 */
@Configuration
@EnableSwagger2
@ComponentScan(basePackages = {"com.juzi.controller"})
public class SwaggerConfig {

    @Bean
    public Docket customDocket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }


    /**
     * Api文档信息
     *
     * @return
     */
    private ApiInfo apiInfo() {
        Contact contact = new Contact("桔子", "https://juzibiji.top", "juzi214032@qq.com");
        return new ApiInfoBuilder()
                .title("项目标题")
                .description("项目描述")
                .contact(contact)
                .version("版本")
                .build();
    }
}

首先使用@Configuration声明当前类为配置类,@EnableSwagger2启用swagger,@ComponentScan指明Controller在哪个包下,swagger就会去扫描这个包。不填的话,swagger应该是会扫描整个项目,性能上可能有一点影响。

ApiInfo中的信息都是会显示在swagger-ui首页的,然后使用@Bean注解向Spring容器中注入一个Docket对象。

3、开启swagger

现在配置类创建好了,但是spring并不知道这里有个配置类,所以我们需要告诉spring,hey,这里有个配置类,快把它加载进去。如果你的项目本身就是用java类配置的,你应该知道怎么做。但如果你的项目是基于XML的话,要将java配置导入xml中,有两种方式:

(1).使用<context:component-scan />标签

像下面这样,多个包用英文逗号隔开,config包就是我们放配置类的地方:

<context:component-scan base-package="edu.uddp.controller,edu.uddp.config,edu.uddp.util"/>

(2).使用<bean />标签

<bean class="edu.uddp.config.SwaggerConfig" />

到此,swagger就已经配置好了,接下来就可以使用注解对api进行说明了。

Last modification:November 14th, 2019 at 12:35 pm