springBoot集成API文档工具Swagger2

一、Swgger介绍

1.官网

https://swagger.io/

2.介绍

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。
3.Swagger的优势
支持API自动生成同步文档，使用Swagger之后可以直接通过代码以及简单的配置来自动生成文档，不再需要手动写接口文档，对于程序员来说，可以节约写文档的时间，来学习新的技术
提供web页面的在线测试API,可以不需要postman等工具进行接口测试，在线测试参数与格式都确定了，直接在web界面进行参数设置就可以测试接口啦。

二、springBoot集成Swagger

1.新建springBoot，导入相关依赖

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

2.新建HelloController控制类接口，然后新建Swagger配置类

因为此类是配置类，所以加入注解@Configuration,Swgger注解@EnableSwagger2表示开启swagger，这样做便可以简单使用Swagger，但是所有配置都执行默认选项

 在浏览器根路径加/swagger-ui.html，便可以访问web端API文档

此图为所有默认配置，在页面可以看到主要分为四个部分，载接口部分basic-error-controller为自带的，比如访问页面为404或者其他则默认走这个路径，Hello-controller为我们新建的Controller,当然我们要根据需要和双方人员需要来进行配置swagger，让他成为一个简单明了得api生成工具

@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //RequestHandlerSelectors配置要扫描接口的方式
                //basePackage表示指定扫描的包
                .apis(RequestHandlerSelectors.basePackage("com.example.demo03.controller"))
                //paths表示需要过滤得路径
                .paths(PathSelectors.any())
                .build();
    }

    //apiInfo为配置Swagger的apiInfo信息
    private ApiInfo apiInfo(){
        Contact contact = new Contact("liufuqiang", "https://cnblogs.com/LiuFqiang", "2895911487@qq.com");
        return new ApiInfo(
                "门诊用药分析系统后台RESTful API文档",
                "author:liufuqiang",
                "v1.0",
                "https://cnblogs.com/LiuFqiang",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

　　这里我们进行简单的配置，Docket为Swagger的实例，通过看底层源码我们可以看到Docket有一些属性

 而我们要很好的使用Swagger需要配置这些属性，比如这里修改api的基本信息，以及指定需要扫面的包

三、环境切换

当我们在正常开发的时候，会有开发环境和生产环境，如果在线上的环境将这个文档直接暴露可能不太好，所有我们得根据想对应的项目环境来改变是否开启Swagger

 api信息不变，增加属性Environment来监听这个项目的环境，如果为开发环境，设置开启Swagger，如果为生成环境，禁用Swagger，比如这里我们启用3030的生成环境，则会出现下面这个界面：

四、文档分组 

给API文档分组，当我们 进行团队开发的时候，最好是将每一个人的文档进行分组以便前端开发人员使用,

 当多人开发的时候，会为spring容器自动注入多个Docket实例，

 我们可以看到在右上角多了几个空间，因为我们注入了三个对应的实例，otherA与otherB由于我们没有任何配置，所以会出现我们第一步的默认配置页面

五、代码注释

当我们在controller返回数据时，如果有涉及pojo类的数据，则这个实体类会被显示在model上

@RestController
public class HelloController {

    @Autowired
    private HelloService helloService;

    @GetMapping("/getAllUser")
    public Student getAllUser(){
        return new Student();
        
    }
}

　这里我们新建实体类Student，在HelloController类中有方法中返回实体类

 在多人开发时可能最痛苦的事情就是看别人写的代码，可能有些字段命名别人看不懂，所有在代码里面注释就会生成文档

 

 当然我们也可以在请求的参数、接口名来进行注释

六、在线测试

点击某个方法的try it out

然后点Execute执行发送请求来进行线上接口测试