springboot+Swagger

项目目录

在这里插入图片描述

pom.xml

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

Controller

写一个HelloController：

@RestController
@RequestMapping("/Hello")
public class HelloController {
    @GetMapping("/hello")
    public String hello(){
        return "hello";
    }
    @GetMapping("/World")
    public String world(){
        return "world";
    }
    @GetMapping("/helloWorld")
    public String helloWorld(){
        return "helloWorld";
    }
}

SwaggerConfig


import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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 {
    //配置Swagger的Docket实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .select()
                //RequestHandlerSelectors配置扫描接口的方式（还有any，none等），
                //basePackage：指定要扫描的包    
                .apis(RequestHandlerSelectors.basePackage("com.jarvis.springbootswagger.controller"))  
                .paths(PathSelectors.ant("/Hello/hello*"))  //url过滤
                .build();
    }
    //配置swagger-ui.html的页面信息
    private ApiInfo apiInfo(){
        return new ApiInfo(
                "jarvis的Swagger-Api文档",
                "感受冥族十万年的怒火吧~~永恒之夜！",
                "v1.0",
                "urn:tos",
                 new Contact("jarvis", "https://blog.csdn.net/weixin_43283513", "[email protected]"),  //作者信息
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                 new ArrayList<>());
    }
}

测试

输入：http://localhost:8080/swagger-ui.html
在这里插入图片描述

在不同环境中配置是否启用Swagger

在这里插入图片描述

application.properties:

spring.profiles.active=dev   //当前环境为开发环境

假如只在开发环境和测试环境中启用Swagger，需要在docket方法中为Docket实例注入enable属性：

@Bean
public Docket docket(Environment environment){
    //设置在dev和test环境下启用swagger
    Profiles profiles = Profiles.of("dev","test");

    //判断是否处在设定的环境当中
    boolean b = environment.acceptsProfiles(profiles);

    return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
            .enable(b)  //enable默认为true，设置为false表示关闭swagger
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.jarvis.springbootswagger.controller")) 
            .paths(PathSelectors.ant("/Hello/hello*")) 
            .build();
}

在dev环境下可以正常访问swagger-ui.html；如果切换为pro环境：spring.profiles.active=pro
在这里插入图片描述

分布式项目中配置Swagger

项目结构：
父工程：guli_parent
一级模块：common、service
二级模块：service-base、service-edu
common为公共模块，将Swagger的配置写在common的子模块service-base中
在这里插入图片描述
common的pom.xml

<artifactId>common</artifactId>
 <!--common为pom类型的maven项目-->
<packaging>pom</packaging>
<modules>
    <module>service-base</module>
    ...common的子模块列表
</modules>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
     <!--引入swagger的依赖-->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
    </dependency>
</dependencies>

service-base子模块中配置Swagger

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;

@Configuration
@EnableSwagger2  //开启Swagger2
public class SwaggerConfig {
    //配置Swagger的Docket实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("WebApi")
                .apiInfo(apiInfo())
                .select()
                .build();
    }
    //配置swagger-ui.html的页面信息
    private ApiInfo apiInfo(){
        return new ApiInfo(
                "jarvis的Swagger-Api文档",
                "感受冥族十万年的怒火吧~~永恒之夜！",
                "v1.0",
                "urn:tos",
                new Contact("jarvis", "https://blog.csdn.net/weixin_43283513", "[email protected]"),  //作者信息
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>());
    }
}

在service模块中引入，使得service下的子模块都可以访问到这个依赖

<artifactId>service</artifactId>
    <!--service为pom类型的maven项目-->
    <packaging>pom</packaging>
<modules>
    <module>service-edu</module>
    ...  //service下的子模块列表
</modules>

<dependencies>
     <!--引入service-base的依赖，使用Swagger2-->
     <dependency>
         <groupId>com.jarvis</groupId>
         <artifactId>service-base</artifactId>
         <version>0.0.1-SNAPSHOT</version>
     </dependency>
     ... 其他依赖
</dependencies>

service-edu子模块中的启动类扫描在common的service-base子模块中的Swagger配置类

@SpringBootApplication
@MapperScan("com.jarvis.eduservice.mapper")
@ComponentScan(basePackages = "com.jarvis")  //增加该注解，因为service-base的包结构和service-edu的包结构都是com.jarvis....
public class ServiceeduApplication {
    public static void main(String[] args) {
        SpringApplication.run(ServiceeduApplication.class,args);
    }
}

Swagger注解

接口上的注解：@Api 、@ApiOperation 、@ApiParam 可以在swagger页面上显示描述

@Api(tags = "讲师管理")
@RestController
@RequestMapping("/eduservice/eduTeacher")
public class EduTeacherController {
    @Autowired
    private EduTeacherService teacherService;

    @ApiOperation(value = "根据id逻辑删除讲师")
    @DeleteMapping("/delete/{id}")
    public Boolean delTeacher(
            @ApiParam(name = "id",value = "讲师id",required = true) @PathVariable String id
    ){

        boolean b = teacherService.removeById(id);
        return b;
    }
}

entity上的注解：@ApiModel 、@ApiModelProperty

@Data
@EqualsAndHashCode(callSuper = false)
@ApiModel(value="EduTeacher对象", description="讲师")
public class EduTeacher implements Serializable {
    private static final long serialVersionUID = 1L;

    @ApiModelProperty(value = "讲师ID")
    @TableId(value = "id", type = IdType.ASSIGN_ID)
    private String id;

    @ApiModelProperty(value = "讲师姓名")
    private String name;
    ...
}