Swagger Learning Notes

背景

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

什么是swagger

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

官网：https://swagger.io/

swagger2+ui

 

使用swagger

springboot集成swagger

 1.新建一个springboot web 项目

 2.导入相关依赖

        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger-uiartifactId>
            <version>2.9.2version>
        dependency>
        
        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger2artifactId>
            <version>2.9.2version>
        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 [email protected]
 * @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 [email protected]
 * @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的bean实例

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 [email protected]
 * @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", "[email protected]");

        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 [email protected]
 * @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", "[email protected]");

        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

配置Api文档的分组

 

 

 

 

 

 

 

参考相关博客：

https://blog.csdn.net/sanyaoxu_2/article/details/80555328

https://www.jianshu.com/p/349e130e40d5