SpringBoot中集成Swagger入门

SpringBoot项目

随便写一个controller作为例子

package com.demo.swagger.controller;

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

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

导入相关依赖

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

最新的version可以在 https://mvnrepository.com/ 搜索springfox

创建Swagger配置文件

package com.demo.swagger.config;

import org.springframework.beans.factory.annotation.Value;
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
public class SwaggerConfig {

    @Bean
    public Docket docket() {

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("铁锤妹妹")
                //是否启动Swagger
                .enable(true)
                .select()
                //配置要扫描接口的方式
                //basePackage:指定要扫描的包 一般用这个
                //any():扫描全部
                //none():不扫描
                //withClassAnnotation:扫描类上的注解，参数是一个注解的反射对象 什么什么.class
                //withMethodAnnotation:扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.demo.swagger.controller"))
                //扫描什么路径
                .paths(PathSelectors.ant("/demo/**"))
                .build();
    }

    private ApiInfo apiInfo() {
        //作者信息
        Contact contact = new Contact("铁锤妹妹头发多","https://blog.csdn.net/SSS_Benjamin","sdrzcx99@sina.com");

        return new ApiInfo(
                "铁锤妹妹的API文档",
                "爱你的铁锤妹妹",
                "1.0",
                "https://blog.csdn.net/SSS_Benjamin",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licences/LICENCE-2.0",
                new ArrayList()
        );
    }
}

打开Swagger页面

http://localhost:8080/swagger-ui.html#/

页面中的内容可以在配置文件中匹配，就能知道配置文件中都配置了什么

补充下面两点

配置是否启动Swagger

若在发布后被别人看到API文档是不安全的，所以要在发布后关闭Swagger
可以引用在SpringBoot项目的配置文件中的变量来控制Swagger的启动

请求方式

展开hello-controller，每一个接口的前面会有请求方式

如果将该接口改为@RequestMapping("/hello")会显示很多种请求方式

API分组

Swagger页面右上角那个下拉框就是分组，团队协作时多个人开发API时可以创建每个人自己的分组
多个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");
}

详细描述

描述Controller类

package com.demo.swagger.controller;

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

@RestController
@RequestMapping("/demo")
@Api(tags = {"Hello接口"})
public class HelloController {
    @GetMapping("/hello")
    public String hello() {
        return "hello";
    }
}

描述实体类

package com.demo.swagger.entity;

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

@ApiModel("用户实体类")
public class User {

    @ApiModelProperty("用户名")
    public String username;

    @ApiModelProperty("密码")
    public String password;
}

在接口中实体类作为返回值的才会显示在Swagger中

描述方法

@GetMapping("/show")
@ApiOperation("显示一个用户")
@ApiResponses(value = {
         @ApiResponse(code = 200, message = "保存成功"),
         @ApiResponse(code = 401, message = "没有权限"),
         @ApiResponse(code = 403, message = "被禁止访问"),
         @ApiResponse(code = 404, message = "没有找到")
 }
 )
 public User showUser(@ApiParam("用户名") @RequestParam("username") String username, @ApiParam("密码") @RequestParam("passwd") String password){
     User user = new User();
     user.setUsername(username);
     user.setPassword(password);
     return user;
 }