Spring Boot:Swagger学习笔记

Spring Boot:Swagger学习笔记

什么是Swagger

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
其作用在于可以在线生成接口文档，帮助测试。
使用Swagger需要在spring配置类上注释
@EnableSwagger2
来开启Swagger功能，访问Swagger页面只需访问url:/swagger-ui.html

依赖

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

配置类

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

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

    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("A");  //不能重名
    }

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

        //设置要显示的Swagger环境
        Profiles profiles = Profiles.of("dev","test");
        //获取项目的环境  通过environment.acceptsProfiles判断是否处在自己设定的环境中，当处于上面profiles指定的环境时，返回true否则false
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag) //是否启用swagger
                .groupName("自己署名") //配置API文档分组
                .select() //select -- build中间写apis或paths
                //apis.any()扫描全部  none()不扫描  withClassAnnotation()扫描类上的注解 withMethodAnnotation()扫描方法下的注解
                .apis(RequestHandlerSelectors.basePackage("com.huang.controller"))   //指定扫描哪个包下的接口
                //paths()过滤什么路径  ant()只扫描/huang/路径下的接口
                .paths(PathSelectors.ant("/huang/**"))
                .build();
    }

    //配置swagger信息=apiInfo
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("自己署名", "自己的网站", "123456789@qq.com");
        return new ApiInfo("**的API文档","描述。。。。","v1.0","自己的网站",contact,"Apache 2.0","http://www.apache.org/licenses/LICENSE-2.0",new ArrayList());
    }
}

网站上线运行后应该切换开发环境不显示Swagger，通过Docket.enable实现。

如上开发环境只需在默认application中配置选用哪个环境即可，例：

spring.profiles.active=dev

配置spring.profiles.active选中dev环境。

controller

package com.huang.controller;

import com.huang.pojo.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/huang")
public class HelloController {
    @GetMapping("/hello")
    public String hello(){
        return "hello";
    }

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

    @PostMapping("/hello2")
    //接口注释
    @ApiOperation("Hello类")
    //属性注释
    public String hello2(@ApiParam("用户名") String username){
        return "hello"+username;
    }

    @PostMapping("/postt")
    @ApiOperation("Post测试类")
    public User u(User user){
        return user;
    }
}

POJO

package com.huang.pojo;

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

//给实体类添加注释
@ApiModel("用户实体类")
public class User {
    //给实体类属性添加注释
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;

    public User() {
    }

    public User(String username, String password) {
        this.username = username;
        this.password = password;
    }

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}