Swagger简单使用之从入门到精通

Swagger简介

        1、Swagger 是一个规范和完整的框架，用于生成、描述、调用。

        2、号称世界上最流行的Api框架。

        3、RestFul Api文档在线自动生成工具（Api文档与Api定义同步更新）

        4、支持多种语言。

官网：API Documentation & Design Tools for Teams | Swagger

简单使用Swagger

在项目中使用Swagger，需要SpringBox（swagger2、swagger-ui）。

        1、SpringBoot集成Swagger

                1.1、新建一个SpringBoot的Web项目

                1.2、导入相关Maven依赖

 注：需要注意SpringBoot与Swagger版本，不然会报错。若springboot项目的版本低，相应的swagger版本不能太高，反之亦然。（这里使用SpringBoot版本为：2.4.1、Swagger版本为2.9.2）

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

                1.3、配置Swagger     

package com.yang.swagger.config;

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

//配置进SpringBoot中
@Configuration
//开启Swagger2
@EnableSwagger2
public class SwaggerConfig {

    //配置Swagger的Docket的Bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                //.enable(true/false):// 是否启用Swagger
                .apiInfo(apiInfo())
                .select()
                //RequestHandlerSelectors：配置要扫描接口的方式
                    //basePackage:指定需要扫描的包(推荐使用)
                    //any:扫描全部
                    //none：都不扫描
                    //withClassAnnotation:扫描类上的注解,RequestHandlerSelectors.withClassAnnotation(RestController.class)
                    //withMethodAnnotation：扫描方法上的注解,RequestHandlerSelectors.withMethodAnnotation(GetMapping.class)
                .apis(RequestHandlerSelectors.basePackage("com.yang.swagger.controller"))
                //PathSelectors：过滤
                    //ant("/Yang/**"): 只过滤出'Yang'下的所有接口
                    //any():过滤全部
                .paths(PathSelectors.any())
                .build();
    }

    //配置Swagger信息的apiInfo
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("Yang"
                , "https://blog.youkuaiyun.com/qq_42696004?spm=1000.2115.3001.5343"
                , "1102046099@qq.com");

        return new ApiInfo(
                "杨的SwaggerAPI文档",    //标题
                "不行不想努力",    //个人简述
                "1.0",               //版本号
                "https://blog.youkuaiyun.com/qq_42696004?spm=1000.2115.3001.5343",  //组织地址
                contact,                     //作者信息
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

}

                1.4、测试运行（访问http://localhost:8080/swagger-ui.html即可）

（默认显示）

（配置后显示）

配置Api文档的分组

 

接口注释        

        @Api : 用在类上，说明该类的主要作用。

        @ApiOperation：用在方法上，给API增加方法说明。

        @ApiImplicitParams : 用在方法上，包含一组参数说明。

        @ApiImplicitParam：用来注解来给方法入参增加说明。

        @ApiModel：用在返回对象类上，描述一个Model的信息。

总结

        我们可以通过Swagger给一些比较难理解的属性或接口，增加注释消息。接口文档实时更新。可以在线测试。

出于安全考虑，且能节省运行的内存，若项目正式发布，建议关闭Swagger！！！！