Springboot 整合 swagger

版權聲明：本文為部落客原創文章，未經部落客允許不得轉載。 https://blog.csdn.net/weixin_40254498/article/details/83622098

swagger

主要是為後端服務的接口文檔，懶人必備，swagger就是一款讓你更好的書寫API文檔的架構。

其他的架構有阿裡爸爸推出

Rap

，感興趣的可以自己了解一下。

本文主要基于springboot，要先了解下springboot；

開始

Maven

本項目基于maven

springboot pom 中添加

<!-- swagger -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.5.0</version>
        </dependency>
        <!-- swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.5.0</version>
        </dependency>
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup-spring-restdocs-ext</artifactId>
            <version>2.5.0</version>
            <scope>test</scope>
        </dependency>
           

啟動

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.boot.autoconfigure.SpringBootApplication;

/**
 * @author Dwxqnswxl
 */
@EnableAutoConfiguration
@SpringBootApplication(scanBasePackages = "com.example")
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

           

配置

import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Description
 *
 * @Author : huangjinxing
 * @Email : [email protected]
 * @Date : 2018/10/24 11:10
 * @Version :
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket swaggerSpringMvcPlugin() {
        return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).build();
    }

    @Bean
    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口清單 v1.1.0")
                .description("接口測試")
                .termsOfServiceUrl("http://localhost:8080/")
                .contact(new Contact("HUANGJINXING","www.dwxqnswxl.cn","[email protected]"))
                .version("1.1.0")
                .build();
    }

}
           

Controller

package com.example.controller;

import com.example.bean.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.context.request.async.DeferredResult;

import java.util.HashMap;
import java.util.Map;

/**
 * Description
 *
 * @Author : huangjinxing
 * @Email : [email protected]
 * @Date : 2018/10/24 11:12
 * @Version :
 */
@Api()
@RestController
@RequestMapping("/demoController")
public class DemoController {

    private static final Logger log = LoggerFactory.getLogger(DemoController.class);

    public static final String RET_CODE = "retCode";
    public static final String RET_MSG = "retMsgo";

    @ApiOperation(value = "新增使用者", notes = "新增注冊")
    @PostMapping(value = "/createUser", consumes = MediaType.APPLICATION_JSON_VALUE)
    public DeferredResult createUser(@RequestBody User user) {
        log.info("createUser:::" , user.toString());
        DeferredResult deferredResult = new DeferredResult();
        Map map = new HashMap();
        map.put(RET_CODE, HttpStatus.OK.value());
        map.put(RET_MSG, "新增成功.");
        deferredResult.setResult(map);
        return deferredResult;
    }

    @ApiOperation(value = "修改使用者", notes = "修改使用者")
    @PostMapping(value = "/updateUser", consumes = MediaType.APPLICATION_JSON_VALUE)
    public DeferredResult updateUser(@RequestBody User user) {
        log.info("updateUser:::" , user.toString());
        DeferredResult deferredResult = new DeferredResult();
        Map map = new HashMap();
        map.put(RET_CODE, HttpStatus.OK.value());
        map.put(RET_MSG, "修改成功.");
        deferredResult.setResult(map);
        return deferredResult;

    }

    @ApiOperation(value = "删除使用者", notes = "删除使用者")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "userId", value = "使用者辨別", required = true, paramType = "query", dataType = "String")
    })
    @DeleteMapping(value = "/deleteUser")
    public DeferredResult deleteUser(@RequestParam("userId") String userId) {
        log.info("deleteUser:::" , userId);
        DeferredResult deferredResult = new DeferredResult();
        Map map = new HashMap();
        map.put(RET_CODE, HttpStatus.OK.value());
        map.put(RET_MSG, "删除成功.");
        deferredResult.setResult(map);
        return deferredResult;
    }

    @ApiOperation(value = "查詢使用者", notes = "查詢使用者")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "userId", value = "使用者辨別", required = true, paramType = "query", dataType = "String")
    })
    @GetMapping(value = "/queryUser")
    public DeferredResult queryUser(@RequestParam("userId") String userId) {
        log.info("queryUser:::" , userId);
        DeferredResult deferredResult = new DeferredResult();
        Map map = new HashMap();
        map.put(RET_CODE, HttpStatus.OK.value());
        map.put(RET_MSG, "查詢成功.");
        map.put("username", "張三.");
        map.put("password", "123456");
        deferredResult.setResult(map);
        return deferredResult;
    }
}

           

User類

package com.example.bean;

/**
 * Description
 *
 * @Author : huangjinxing
 * @Email : [email protected]
 * @Date : 2018/10/24 11:16
 * @Version :
 */
public class User {

    private String username;
    private String 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;
    }

    @Override
    public String toString() {
        return "User{" +
                "username='" + username + '\'' +
                ", password='" + password + '\'' +
                '}';
    }
}

           

登陸 http://localhost:8080/swagger-ui.html#/
就可以看到有UI的 接口 
swagger的功能不止如此。
           

效果