Swagger的使用

pom

            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>${swagger.version}</version>
            </dependency>
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>${swagger.version}</version>
            </dependency>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.6</version>
                <configuration>
                    <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
                    <outputDirectory>src/docs/asciidoc/html</outputDirectory>
                    <backend>html</backend>
                    <sourceHighlighter>coderay</sourceHighlighter>
                    <attributes>
                        <toc>left</toc>
                    </attributes>
                </configuration>
            </plugin>
        </plugins>
    </build>

配置

package com.eding.kwafoo.sys.config;

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.service.Contact;
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 api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.eding.kwafoo.sys.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiEndPointsInfo())
                .useDefaultResponseMessages(false);
    }

    private ApiInfo apiEndPointsInfo() {
        return new ApiInfoBuilder().title("Sys REST API")
                .description("Kwafoo Sys REST API")
                .contact(new Contact("Zhangln", "https://code.aliyun.com/yidingv3/kwafoo", "zhangln@zhidianfan.com"))
                .license("edingyi")
                .licenseUrl("http://www.edingyi.com")
                .version("V1")
                .build();
    }
}

执行

package com.eding.kwafoo.sys.controller;

import io.github.swagger2markup.Swagger2MarkupConfig;
import io.github.swagger2markup.Swagger2MarkupConverter;
import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
import io.github.swagger2markup.markup.builder.MarkupLanguage;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit4.SpringRunner;

import java.net.URL;
import java.nio.file.Paths;

/**
 * @author sherry
 * @description
 * @date Create in 2020/1/2
 * @modified By:
 */
@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)
public class ApiDocumentGenerator {
    @Test
    public void generateAsciiDocs() throws Exception {
        //    输出Ascii格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .build();

        Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFile(Paths.get("src/docs/asciidoc/generated/all"));
    }
}

使用案例

package com.eding.kwafoo.sys.controller;

import com.eding.kwafoo.common.constant.BusinessType;
import com.eding.kwafoo.common.constant.ModuleName;
import com.eding.kwafoo.common.constant.RocketMqConstant;
import com.eding.kwafoo.common.dto.BaseResponse;
import com.eding.kwafoo.common.dto.BusinessLogDto;
import com.eding.kwafoo.common.enums.ClientType;
import com.eding.kwafoo.common.mq.RocketMQSysProducer;
import com.eding.kwafoo.common.util.KwafooUtil;
import com.eding.kwafoo.common.util.ByteArrayUtils;
import com.eding.kwafoo.common.util.WebUtil;
import com.eding.kwafoo.sys.dto.ConfigDictAddDto;
import com.eding.kwafoo.sys.dto.ConfigDictDto;
import com.eding.kwafoo.sys.dto.ConfigDictListDto;
import com.eding.kwafoo.sys.dto.Test1Request;
import com.eding.kwafoo.sys.service.SysService;
import com.github.structlog4j.ILogger;
import com.github.structlog4j.SLoggerFactory;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;

import java.time.LocalDateTime;
import java.util.Date;
import java.util.List;

/**
 * @author sherry
 * @description
 * @date Create in 2019/12/17
 * @modified By:
 */
@Api("系统管理")
@RestController
@RequestMapping("/v1/sys")
public class SysController {

    static final ILogger log = SLoggerFactory.getLogger(SysController.class);
    @Autowired
    private RocketMQSysProducer producer;

    @Autowired
    private SysService sysService;

    @ApiOperation("新增批量码表")
    @PostMapping("/add_config_dict_list")
    public BaseResponse addConfigDictList(@Validated @RequestBody ConfigDictListDto configDictListDto) {
        sysService.addConfigDictList(configDictListDto);
        return BaseResponse.builder().build();
    }

    @ApiOperation("新增单个码表")
    @PostMapping("/add_config_dict_one")
    public BaseResponse addConfigDictOne(@Validated ConfigDictAddDto configDictAddDto) {
        sysService.addConfigDictOne(configDictAddDto);
        return BaseResponse.builder().build();
    }

    @ApiOperation("码表查询")
    @GetMapping("/get_config_dict_by_type")
    public BaseResponse<List<ConfigDictDto>> getConfigDictByType2(@ApiParam(name = "type", required = true, value = "码表类型") @RequestParam String type) {

        List<ConfigDictDto> list = sysService.getConfigDictByType(type);

        BaseResponse<List<ConfigDictDto>> baseResponse = new BaseResponse<>(list);
        return baseResponse;
    }

    @ApiOperation(value = "测试", notes = "测试说明", httpMethod = "POST")
    @PostMapping("/test1")
    public BaseResponse test1(@Validated @RequestBody Test1Request request) {

        log.info("获取请求头 userId ：" + WebUtil.getHeader("userId"));
        log.info("获取请求头 orgId ：" + WebUtil.getHeader("orgId"));

        log.info(request.getUsername() + ":" + request.getNow());


//        假装发送一笔短信
        BusinessLogDto businessLogDto = new BusinessLogDto(ModuleName.LOG, this.getClass().getName() + "." + Thread.currentThread().getStackTrace()[1].getMethodName()
                , ClientType.SYS_MOBILE_SERVER.name()
                , Long.valueOf(WebUtil.getHeader("orgId"))
                , Long.valueOf(WebUtil.getHeader("userId")), BusinessType.SMS
                , BusinessType.SMS_SEND, 1, "发送成功", LocalDateTime.now());
        KwafooUtil.sendBusinessLog(this.producer.getProducer(), RocketMqConstant.TOPIC_SYS, RocketMqConstant.TAGS_SYS_BUSINESS, ByteArrayUtils.objectToBytes(businessLogDto).get());
        return BaseResponse.builder().message("成功" + new Date()).build();
    }

}

package com.eding.kwafoo.sys.dto;

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

import javax.validation.constraints.NotEmpty;

/**
 * @author sherry
 * @description
 * @date Create in 2020/1/8
 * @modified By:
 */
@ApiModel(value = "ConfigDictAddDto", description = "新增单个码表")
@Data
public class ConfigDictAddDto {
    @ApiModelProperty(value = "type", required = true, name = "码表类型")
    @NotEmpty
    private String type;
    @ApiModelProperty(value = "code", required = true, name = "编码")
    @NotEmpty
    private String code;
    @ApiModelProperty(value = "value", required = true, name = "编码含义")
    @NotEmpty
    private String value;
    @ApiModelProperty(name = "编码详情", value = "descr")
    private String descr;
    @ApiModelProperty(name = "排序字段", example = "1", value = "sortNum")
    private Integer sortNum;
}