Spring Boot: integration Swagger online documentation Spring Boot: Quick Start Tutorial

Comprehensive Overview

spring-boot as the current most popular Java web development Scaffolding, more and more developers choose RESTFul API interfaces with which to build enterprise-class. These interfaces serve not only to traditional web end (b / s), also serve the mobile terminal. In the actual development process, but also to provide these interfaces to develop tests related to white-box testing, then there is bound to share in how people collaborate in the development and timely update API interface documentation problems.

If you have the drawbacks of traditional wiki document sharing brought hate, then try Swagger2 way, we will let you have a different development experience.

Use Swagger integrated document has the following advantages:

Feature-rich: supports multiple annotations automatically generate interfaces document interface, support for testing API interface functions in the interface;
Update: the development process to take the time to write a little comment, allows you to quickly update the API documentation, worry and effort;
Integration is simple: by adding pom dependencies and simple configuration, can be embedded in applications also released API interface documentation interface, you do not need to deploy a separate service.

Implementing stories

Next, we come to realize the function integration Swagger online API documentation by Spring Boot.

Build the project template

In order for us to initialize the project, Spring Boot provides us with a project template to create website.

1. Open your browser, visit: https://start.spring.io/

The page prompts, select the build tool, language development, project information.

3. Click Generate the project, build the project template, will be generated after the archive downloaded to the local.

4. Use the IDE to import project, here I use Eclipse, imported by importing Maven project.

Add the relevant dependent

Add Maven its dependencies, you need to add here and SWAGGER dependent on the WEB.

WEB-dependent

<dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
</dependency>

swagger依赖，这里选择 2.9.2 版本。

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

添加配置类

添加一个swagger 配置类，在工程下新建 config 包并添加一个 SwaggerConfig 配置类。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("Kitty API Doc")
                .description("This is a restful api document of Kitty.")
                .version("1.0")
                .build();
    }

}

添加控制器

添加一个控制器，在工程下新建 controller包并添加一个 HelloController控制器。

package com.louis.springboot.demo.controller;

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

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;

/* 类注解 */
@Api(value = "desc of class")
@RestController
public class HelloController {

    /* 方法注解 */
    @ApiOperation(value = "desc of method", notes = "")
    @GetMapping(value="/hello")
    public Object hello( /* 参数注解 */ @ApiParam(value = "desc of param" , required=true ) @RequestParam String name) {
        return "Hello " + name + "!";
    }
}

编译运行测试

1. 右键项目 -> Run as -> Maven install，开始执行Maven构建，第一次会下载Maven依赖，可能需要点时间，如果出现如下信息，就说明项目编译打包成功了。

2. 右键文件 DemoApplication.java -> Run as -> Java Application，开始启动应用，当出现如下信息的时候，就说明应用启动成功了，默认启动端口是8080。

3. 打开浏览器，访问：http://localhost:8080/swagger-ui.html，进入swagger接口文档界面。

4. 展开hello-controller的hello接口，输入参数并点击执行，就可以看到接口测试结果了。

常用注解说明

swagger 通过注解接口生成文档，包括接口名，请求方法，参数，返回信息等。

@Api: 修饰整个类，用于controller类上

@ApiOperation: 描述一个接口，用户controller方法上

@ApiParam: 单个参数描述

@ApiModel: 用来对象接收参数,即返回对象

@ApiModelProperty: 对象接收参数时，描述对象的字段

@ApiResponse: Http响应其中的描述，在ApiResonse中

@ApiResponses: Http响应所有的描述，用在

@ApiIgnore: 忽略这个API

@ApiError: 发生错误的返回信息

@ApiImplicitParam: 一个请求参数

@ApiImplicitParam: 多个请求参数

更多使用说明，参考 Swagger 使用手册。

添加请求参数

在很多时候，我们需要在调用我们每一个接口的时候都携带上一些通用参数，比如采取token验证逻辑的往往在接口请求时需要把token也一起传入后台，接下来，我们就来讲解一下如何给Swagger添加固定的请求参数。

修改SwaggerConfig配置类，替换成如下内容，利用ParameterBuilder构成请求参数。

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi(){
        // 添加请求参数，我们这里把token作为请求头部参数传入后端
        ParameterBuilder parameterBuilder = new ParameterBuilder();  
        List<Parameter> parameters = new ArrayList<Parameter>();  
        parameterBuilder.name("token").description("令牌")
            .modelRef(new ModelRef("string")).parameterType("header").required(false).build();  
        parameters.add(parameterBuilder.build());  
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                .apis(RequestHandlerSelectors.any()).paths(PathSelectors.any())
                .build().globalOperationParameters(parameters);
//        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
//                .select()
//                .apis(RequestHandlerSelectors.any())
//                .paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("Swagger API Doc")
                .description("This is a restful api document of Swagger.")
                .version("1.0")
                .build();
    }

}