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.導入相關依賴

<!-- 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的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 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());
    }
}

SwaggerConfig

配置Api文檔的分組

 

 

 

 

 

 

 

參考相關博客：

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

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