swagger使用

简介

• 号称世界上最流行的API框架
• Restful API在线文档–API定义与API文档同步更新
• 直接运行，可以在线测试API接口
• 支持多种语言（JAVA,PHP）

官网： https://swagger.io/

使用前需要Springfox

• swagger2
• ui

springboot集成swagger

1.新建springboot-web项目

2.导入相关依赖

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

3.编写Hello工程

HelloController

package com.allen.swagger.controller;

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

/**
 * @author Allen
 * @date 2020/12/29 21:32
 */

@RestController
public class HelloController {

    @RequestMapping("/hello")
    public String hello(){
        return "hello, swagger!";
    }
}

4.配置swagger, 编写config

package com.allen.swagger.config;

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

/**
 * @author Allen
 * @date 2020/12/29 21:35
 */

@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {

}

5.访问 http://localhost:8080/swagger-ui.html

配置Swagger

• Swagger的bean实例Docket

SwaggerConfig

package com.allen.swagger.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;



/**
 * @author Allen
 * @date 2020/12/29 21:35
 */

@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {

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

    //配置swagger的ApiInfo
    public ApiInfo apiInfo(){

        //作者信息
        Contact contact = new Contact("allen", "https://hlgao666.github.io/", "");

        return new ApiInfo(
                "allen's diary",
                "never give up",
                "1.0",
                "https://hlgao666.github.io/",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

}

swagger配置扫描接口

SwaggerConfig

    //配置swagger的bean实例Docket
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //RequestHandlerSelectors 配置要扫描接口的方式
                //basePackage指定要扫描的包
                //any()扫描全部
                //none()均不扫描
                .apis(RequestHandlerSelectors.basePackage("com.allen.swagger.controller"))
                //paths() 过滤什么路径
                .paths(PathSelectors.ant("/allen/**"))
                .build();   //build工厂模式
    }

配置是否启动swagger

enable()是否启动swagger，如果false，不能启动

    //配置swagger的bean实例Docket
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //enable()是否启动swagger，如果false，不能启动
                .enable(false)
                .select()
                //RequestHandlerSelectors 配置要扫描接口的方式
                //basePackage指定要扫描的包
                //any()扫描全部
                //none()均不扫描
                .apis(RequestHandlerSelectors.basePackage("com.allen.swagger.controller"))
                //paths() 过滤什么路径
                //.paths(PathSelectors.ant("/allen/**"))
                .build();   //build工厂模式
    }

配置不同环境下启动swagger

在开发环境启动swagger

1.编写多个properties文件

application.properties

spring.profiles.active=dev

application-dev.properties

server.port=8081

application-pro.properties

server.port=8082

2.通过environment.acceptsProfiles判断是否是自己设定的环境

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

        //设定开启swagger的环境
        Profiles profiles = Profiles.of("dev","test");

        //通过environment.acceptsProfiles判断是否是自己设定的环境
        boolean flag = environment.acceptsProfiles(profiles);


        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //enable()是否启动swagger，如果false，不能启动
                .enable(flag)
                .select()
                //RequestHandlerSelectors 配置要扫描接口的方式
                //basePackage指定要扫描的包
                //any()扫描全部
                //none()均不扫描
                .apis(RequestHandlerSelectors.basePackage("com.allen.swagger.controller"))
                //paths() 过滤什么路径
//                .paths(PathSelectors.ant("/allen/**"))
                .build();   //build工厂模式
    }

3.测试

配置分组

.groupName("allen")

配置多个分组

只需在SwaggerConfig中配置多个Docket实例即可，添加代下代码

    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }

    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("B");
    }

    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("C");
    }

给类、属性、控制器添加释义

新建User实体类，注意属性不能是private，否则不会被暴露和注释

package com.allen.swagger.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

/**
 * @author Allen
 * @date 2020/12/30 10:47
 */
@ApiModel("用户实体类")
public class User {

    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;
}

给控制器方法添加注释：放在Controller方法上，添加@ApiOperation

@RestController
public class HelloController {

    //Operation接口，放在方法上
    @ApiOperation("hello控制器")
    @GetMapping("/hello")
    public String hello(){
        return "hello, swagger!";
    }

    //只要接口返回值存在实体类，就会被扫描到swagger中
    @PostMapping("/user")
    public User user(){
        return new User();
    }
}

总结

1. 可以通过swagger给一些较难理解的属性或接口增加注释信息
2. 接口文档实时更新
3. 可以在线测试

注意：在正式发布的时候，需要关闭swagger.出于安全考虑，不暴露接口文档。