swagger入门学习

本文主要是对于swagger非常浅显的知识进行介绍，并不深入了解，只接触表面，对一些较复杂的内容也不过多描述。如文中有错误之处，望不吝赐教，谢谢~

一、swagger概述

swagger是一个API文档工具，通过swagger可以便捷且规范地生成API文档，这有利于前后端开发人员之间的交流：在调用API时有实时规范的API文档供参考。
在这里我们主要是使用swagger2，swagger2可以将项目的所有接口在一个UI界面（swagger-ui.html）上展示出来，同时表明了这个接口的用途，接口需要的参数是什么类型参数是否必须，输入了参数可以直接测试接口类似postman的功能，会显示接口请求的状态码和返回的数据结构。

二、swagger2简单实例

（1）新建spring boot项目。
（2）引入swagger2依赖。

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

（3）配置不同的环境
由于API文档属于开发者层面的内容，因此其不愿意也不希望被用户和其他人员看到，故配置不同的环境，在正式发行时要删除swagger，以防用户看到。

• 开发环境（面向开发人员）
  application-dev.properties

#开发环境端口为8081
server.port=8081

• 正式发行环境（面向用户）
  application-pro.properties

#开发环境端口为8082
server.port=8082

现在我们处于开发阶段，因此将环境配置成生成环境。
application.properties

#生产环境
spring.profiles.active=dev

（4）创建相应的swagger2配置类

• swagger实例即为Docket对象
• 根据配置环境决定是否开启swagger，这里是生产环境，故要开启swagger

package com.example.swagger_study_demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
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;

/**
 * @className: SwaggerConfig
 * @description: swagger配置类 
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * 配置swagger实例
     *
     * @return
     */
    @Bean
    public Docket docket(Environment environment) {

        //设置swagger环境
        Profiles profiles = Profiles.of("dev");

        //判断当前swagger是否处于所设置的环境中
        boolean flag = environment.acceptsProfiles(profiles);

        //apiInfo-swagger信息
        //apis RequestHandlerSelectors-配置要扫描接口的方式 ，basePackage-指定要扫描的包
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(flag)
                .apiInfo(apiInfo())
                .select().apis(RequestHandlerSelectors.basePackage("com.example.swagger_study_demo.controller"))
                .build();
    }


    /**
     * 配置swagger信息
     *
     * @return
     */
    private ApiInfo apiInfo() {

        //作者信息
        Contact contact = new Contact("", "", "");

        return new ApiInfo("Api Documentation",
                "Api Documentation",
                "1.0",
                "urn:tos",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>());
    }
}

（5）新建一控制器类用以验证请求。
HelloController.java

package com.example.swagger_study_demo.controller;

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

/**
 * @className: HelloController
 * @description:
 */
@RestController
public class HelloController {

    @GetMapping(value = "/hello")
    public String hello(){

        return "hello";
    }
}

（6）启动项目成功后，在浏览器中输入

http://localhost:8081/swagger-ui.html

注意端口是8081（配置的是生产端口）。即可进入以下页面，

该页面即是用来展示API文档的页面，是由相应的swagger包提供的。图中的信息很多都是默认的，这是由于在生成Docket对象时，有些信息并未配置，这里这是演示swagger的功能，大家可自行配置。
我们重点是在hello-controller上，点击"GET /hello hello"即可打开以下页面

这里展示了HelloController里的hello()请求（方法）的一些信息，通过这些信息前后端开发人员可以很方便知道hello()请求（方法）的一些信息，并且若是hello()请求（方法）修改，相应的文档修改也很方便。

三、总结

• swagger是一款API文档工具，有利于前后端人员调用接口，也是API文档的编写更加规范便捷。
• API文档一般只面向开发人员，对用户不展示。
• 配置swagger，相应的生成Docket对象。
• API接口在swagger-ui.html页面展示。

2020.04.20