Swagger Learning Notes

swagger背景

首先指定schema[计划的提纲]，实时更新最新API,降低集成风险；
早些年：制定word计划文档；
前后端分离：
　　　前端测试后端接口：postman
　　　后端提供接口，需要实时更新最新的消息改动

swagger简介

swagger2可以将项目的所有接口在一个UI界面上展示出来，同时表明了这个接口的用途，接口需要的参数是什么类型参数是否必须，输入了参数可以直接测试接口类似postman的功能，会显示接口请求的状态码和返回的数据结构。

号称世界上最流行的Api框架；
Restful   Api  文档在线自动生成工具 => Api 文档与Api 定义同步更新
直接运行，可以在线测试API接口
支持多种语言

官网：https://swagger.io/

swagger2+ui

swagger应用

springboot集成swagger

1.新建一个springboot web 项目

2.导入相关依赖

<!-- 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>
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

3.编写一个Hello工程

package com.mikey.swagger_demo.controller;

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

/**
 * @ProjectName swagger_demo
 * @Author 麦奇
 * @Email biaogejiushibiao@outlook.com
 * @Date 9/5/19 9:21 AM
 * @Version 1.0
 * @Description:
 **/
@RestController
public class HelloController {

    @RequestMapping("/hello")
    public String hello(){

        return "hello";
    }

}

HelloController

4.配置Swagger

package com.mikey.swagger_demo.config;

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

/**
 * @ProjectName swagger_demo
 * @Author 麦奇
 * @Email biaogejiushibiao@outlook.com
 * @Date 9/5/19 9:25 AM
 * @Version 1.0
 * @Description:
 **/
@Configuration
@EnableSwagger2 //开启swagger
public class SwaggerConfig {
    
}

5.测试页面

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

Swagger配置

package com.mikey.swagger_demo.config;

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

/**
 * @ProjectName swagger_demo
 * @Author 麦奇
 * @Email biaogejiushibiao@outlook.com
 * @Date 9/5/19 9:25 AM
 * @Version 1.0
 * @Description:
 **/
@Configuration
@EnableSwagger2 //开启swagger
public class SwaggerConfig {

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

    //配置swagger信息 apiInfo

    private ApiInfo apiInfo(){

        //作者信息
        Contact DEFAULT_CONTACT = new Contact("麦奇", "www.mikey.com", "biaogejiushibiao@outlook.com");

        return new ApiInfo("麦奇的SwaggerApi文档",
                "描述",
                "v1.0",
                "https://www.cnblogs.com/biaogejiushibiao/",
                DEFAULT_CONTACT,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

SwaggerConfig

Swagger扫描

Docket.select()

package com.mikey.swagger_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.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;

/**
 * @ProjectName swagger_demo
 * @Author 麦奇
 * @Email biaogejiushibiao@outlook.com
 * @Date 9/5/19 9:25 AM
 * @Version 1.0
 * @Description:
 **/
@Configuration
@EnableSwagger2 //开启swagger
public class SwaggerConfig {

    //配置了swagger的docket的bean实例
    @Bean
    public Docket docket(Environment environment){

        //设置要显示的swagger环境
        Profiles profiles = Profiles.of("dev","test");
        //获取项目的环境
        //通过environment.acceptsProfiles判断是否处在自己设定的环境当中
        boolean openSwagger = environment.acceptsProfiles(profiles);


        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //是否启用swagger
                .enable(openSwagger)
                .select()
                //requestHandler 配置要扫描接口方式
                //basePackage 指定扫描包
                //any 扫描全部
                //none 不扫描
                //withClassAnnotation  扫描类上的注解 参数是注解的反射对象
                //withMethodAnnotation  扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.mikey.swagger_demo.controller"))
                //过滤什么路径
                //.paths(PathSelectors.ant("/"))
                .build();
    }

    //配置swagger信息 apiInfo

    private ApiInfo apiInfo(){

        //作者信息
        Contact DEFAULT_CONTACT = new Contact("麦奇", "www.mikey.com", "biaogejiushibiao@outlook.com");

        return new ApiInfo("麦奇的SwaggerApi文档",
                "描述",
                "v1.0",
                "https://www.cnblogs.com/biaogejiushibiao/",
                DEFAULT_CONTACT,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}