Spring Cloud Alibaba-Swagger（七）

时间 2019-11-07

标签 spring cloud alibaba swagger 栏目 Spring 繁體版

原文原文链接

简介

swagger能够方便的帮助咱们构建API文档。官方网站html

效果

项目整合swagger后默认提供两种整合方式java

json(http://localhost:8080/v2/api-docs)

html(http://localhost:8080/swagger-ui.html)

我的认为以上两种方式产生的API文档都不够完美，因此整合插件生成html,放在nginx以供查阅。

步骤以下

运行springboot确保http://localhost:8080/v2/api-docs能够访问
生成ASCIIDOC

生成html

整合swagger

加依赖(给出整个pom)

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.1.9.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.virgo</groupId>
    <artifactId>swagger-demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>swagger-demo</name>
    <description>Demo project for Spring Boot</description>

    <properties>
        <java.version>1.8</java.version>
        <!--swagger-->
        <swagger2markup.version>1.3.1</swagger2markup.version>
        <swagger.springfox.version>2.9.2</swagger.springfox.version>
        <swagger.model.version>1.5.21</swagger.model.version>
        <asciidoctor.version>1.5.6</asciidoctor.version>
        <generated.source.directory>src/docs/asciidoc/generated</generated.source.directory>
        <generated.output.directory>src/docs/asciidoc/generated/all</generated.output.directory>
        <asciidoctor.html.output.directory>src/docs/asciidoc/html</asciidoctor.html.output.directory>
    </properties>

    <!--swagger-->
    <pluginRepositories>
        <pluginRepository>
            <id>jcenter-snapshots</id>
            <name>jcenter</name>
            <url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url>
        </pluginRepository>
        <pluginRepository>
            <id>jcenter-releases</id>
            <name>jcenter</name>
            <url>http://jcenter.bintray.com</url>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </pluginRepository>
    </pluginRepositories>

    <repositories>
        <repository>
            <id>jcentral</id>
            <name>bintray</name>
            <url>http://jcenter.bintray.com</url>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </repository>
        <repository>
            <id>jcenter-snapshots</id>
            <name>jcenter</name>
            <url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url>
        </repository>
    </repositories>

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

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

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>

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

        <!--swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.springfox.version}</version>
            <exclusions>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-annotations</artifactId>
                </exclusion>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-models</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.springfox.version}</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>${swagger.model.version}</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>${swagger.model.version}</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
            <!--swagger-->
            <plugin>
                <groupId>io.github.swagger2markup</groupId>
                <artifactId>swagger2markup-maven-plugin</artifactId>
                <version>${swagger2markup.version}</version>
                <configuration>
                    <swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput>
                    <!-- 生成为单个文档，输出路径 -->
                    <outputFile>${generated.output.directory}</outputFile>
                    <config>
                        <!-- ascii格式文档 -->
                        <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                        <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
                    </config>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>${asciidoctor.version}</version>
                <configuration>
                    <!-- asciidoc文档输入路径 -->
                    <sourceDirectory>${generated.source.directory}</sourceDirectory>
                    <!-- html文档输出路径 -->
                    <outputDirectory>${asciidoctor.html.output.directory}</outputDirectory>
                    <backend>html</backend>
                    <sourceHighlighter>coderay</sourceHighlighter>
                    <!-- html文档格式参数 -->
                    <attributes>
                        <doctype>book</doctype>
                        <!--菜单栏在左边-->
                        <toc>left</toc>
                        <!--多标题排列-->
                        <toclevels>3</toclevels>
                    </attributes>
                </configuration>
            </plugin>
        </plugins>
    </build>

</project>

复制代码

写注解

无
复制代码

写配置

package com.virgo.swaggerdemo.configuration;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
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;

/**
 * @author zhaozha
 * @date 2019/10/12 上午10:05
 */
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("用户中心Restful APIs")
                .description("用户中心API接口文档")
                .termsOfServiceUrl("")
                .version("1.0.0")
                .contact(new Contact("zhao", "", "")).build();
    }

    @Bean
    public Docket customImplementation() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.virgo"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(this.apiInfo()).enable(true);

        //.globalOperationParameters(parameters);
    }
}

复制代码

常见注解

对象	注解	属性	说明
对象	@ApiModel		描述对象总体
		value	描述对象总体
		description	描述对象总体
对象属性	@ApiModelProperty		描述对象属性
		value	描述对象属性
类	@Api		描述类总体
		value	url的路径
		tags	覆盖value
		description	描述
		basePath	基本路径
		position	配置多个Api 想改变显示的顺序位置
		produces	格式如application/json
		consumes	同produces
		protocols	协议如http
		authorizations	认证
		hidden	是否隐藏
方法	@ApiOperation		描述方法总体
		value	url的路径
		tags	覆盖value
		description	描述
		basePath	基本路径
		position	配置多个Api 想改变显示的顺序位置
		produces	格式如application/json
		consumes	同produces
		protocols	协议如http
		authorizations	认证
		hidden	是否隐藏
		response	返回的对象
		responseContainer	返回的集合如List/Map...
		httpMethod	GET/POST...
		code	状态码
		extensions	拓展
方法响应	@ApiResponse		响应
		code	http状态码
		message	描述
		response	响应类
		reference	参考
		responseHeaders	头
		responseContainer
方法响应头	@ResponseHeader		响应头
		name	响应头名称
		description	描述
		response	响应类
		responseContainer
响应集	@ApiResponses		响应集
单个响应	@ApiResponse		响应集中单个响应
		code	http状态码
		message	描述
方法属性	@ApiParam		描述方法属性
		name	属性名称
		value	属性值
		defaultValue	默认属性值
		allowableValues	能够不配置
		required	是否必填
		access
		allowMultiple
		hidden	是否隐藏
		example	举例
属性集	@ApiImplicitParams		属性集
单个属性	@ApiImplicitParam		属性集中单个属性
		paramType
		name	含义
		value	名称
		dataType	类型
		required	是否必填
		defaultValue	默认值

DEMO

gitee.com/dotl/swagge…nginx

安全性说明

不建议让外部人员能够访问内部的api文档,建议添加安全措施或者在SwaggerConfiguration上配置@Profile("dev"),仅仅在开发环境中有效。git

最后

文章如有谬误之处，但愿广大读者指正，互相交流，共同提升。github