Springfox Reference Documentation

最新推荐文章于 2024-07-26 14:54:01 发布

weixin_34221036

最新推荐文章于 2024-07-26 14:54:01 发布

阅读量297

点赞数

文章标签： git json runtime

1. Introduction

The Springfox suite of java libraries are all about automating the generation of machine and human readable specifications for JSON APIs written using the spring family of projects. Springfox works by examining an application, once, at runtime to infer API semantics based on spring configurations, class structure and various compile time java Annotations.

1.1. History

Springfox has evolved from a project originally created by Marty Pitt and was named swagger-springmvc. Much kudos goes to Marty.

1.2. Goals

To extend support for a number of the evolving standards targeted at JSON API specification and documentation such as: swagger, RAML and jsonapi.
To extend support for spring technologies other than spring webmvc
Philosophically, we want to discourage using (swagger-core) annotations that are not material to the service description at runtime. For e.g. the jackson annotations should always trump or have more weight than@ApiModelProperty or for e.g. @NotNull or specifying @RequestParam#required should always win. Annotations are to to be used only to supplement documentation or override/tweak the resulting spec in cases where its not possible to infer service/schema characteristics.

1.3. What it’s not

Endorsed or approved by the Spring Framework Contributors

1.4. Development Environment

File >> open >> build.gradle
Make sure to check the 'use the default gradle wrapper' option.
First time build

./gradlew cleanIdea idea

To get more output from any gradle commands/tasks append a -i (info) or -d (debug) e.g.

./gradlew build -i

To publish to local maven repository

./gradlew clean build publishToMavenLocal -i

This build is optimized for releasing software to bintray/sonatype. In order for gradle to figure out the version the gradle plugin relies on local folder being a cloned git repository. Downloading the source archive and building will NOT work!

1.4.1. Pre-Commit Build

Code quality (code coverage, checkstyle)

./gradlew check

1.4.2. Building reference documentation

To view the docs in a browser run:

./gradlew docs

When frequently generating the docs use the Gradle daemon as follows

 ./gradlew asciidoc --daemon

1.4.3. CI Environment

Circle CI

1.5. Releasing

To release a non-snapshot version of Springfox:

Execute the the release commands: The below properties are required to run a release:
GITHUB_TOKEN
BINTRAY_USERNAME
BINTRAY_PASSWORD

Recommend using [autoenv](https://github.com/kennethreitz/autoenv) with a .env file at the root of the repo.

    ./gradlew release publishDocs -PbintrayUsername=$BINTRAY_USERNAME -PbintrayPassword=$BINTRAY_PASSWORD
    -PreleaseType=<MAJOR|MINOR|PATCH> -i

The release steps are as follows: - check that the git workspace is clean - check that the local git branch is master - check that the local git branch is the same as origin - gradle test - gradle check - upload (publish) all artifacts to Bintray - Bumps the project version in version.properties - Git tag the release - Git push

1.5.1. Snapshot

This is normally done by the CI server

./gradlew snapshot -PbintrayUsername=<bintrayUsername> -PbintrayPassword=<bintrayPassword>

1.5.2. Override deploy

To bypass the standard release flow and upload directly to bintray use the following task - manually set the version in version.properties

./gradlew clean build bintrayUpload -PbintrayUsername=$BINTRAY_USERNAME -PbintrayPassword=$BINTRAY_PASSWORD -PreleaseType=<MAJOR|MINOR|PATCH>
 --stacktrace

1.5.3. Updating documentation

To update the docs for an existing release pass the updateMode switch

./gradlew publishDocs -PupdateMode

1.5.4. Contributing

Please see the wiki for some guidelines

1.6. Support

If you find issues or bugs please submit them via the Springfox Github project

2. Getting Started

2.1. Dependencies

The Springfox libraries are hosted on bintray and jcenter. The artifacts can be viewed accessed at the following locations:

Springfox has multiple modules and the dependencies will vary depending on the desired API specification standard. Below outlines how to include the springfox-swagger2 module which produces Swagger 2.0 API documentation.

2.1.1. Gradle

Release

repositories {
  jcenter()
}

dependencies {
    compile "io.springfox:springfox-swagger2:2.6.1"
}

Snapshot

repositories {
   maven { url 'http://oss.jfrog.org/artifactory/oss-snapshot-local/' }
}

dependencies {
    compile "io.springfox:springfox-swagger2:2.6.2-SNAPSHOT" }

2.1.2. Maven

Release

<repositories>
    <repository>
      <id>jcenter-snapshots</id>
      <name>jcenter</name> <url>https://jcenter.bintray.com/</url> </repository> </repositories> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency>

Snapshot

<repositories>
    <repository>
      <id>jcenter-snapshots</id>
      <name>jcenter</name> <url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url> </repository> </repositories> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.2-SNAPSHOT</version> </dependency>

2.1.3. Springfox-swagger2 with Spring MVC and Spring Boot

/*
 *
 *  Copyright 2015 the original author or authors.
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *         http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 *
 *
 */

package springfox.springconfig;

import com.fasterxml.classmate.TypeResolver;
import org.joda.time.LocalDate; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.context.ApplicationContext; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.ComponentScan; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.RequestMethod; import org.springframework.web.context.request.async.DeferredResult; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.builders.ResponseMessageBuilder; import springfox.documentation.builders.ParameterBuilder; import springfox.documentation.schema.ModelRef; import springfox.documentation.schema.WildcardType; import springfox.documentation.service.ApiKey; import springfox.documentation.service.AuthorizationScope; import springfox.documentation.service.SecurityReference; import springfox.documentation.service.Tag; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spi.service.contexts.SecurityContext; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger.web.ApiKeyVehicle; import springfox.documentation.swagger.web.SecurityConfiguration; import springfox.documentation.swagger.web.UiConfiguration; import springfox.documentation.swagger2.annotations.EnableSwagger2; import springfox.petstore.controller.PetController; import java.util.List; import static com.google.common.collect.Lists.*; import static springfox.documentation.schema.AlternateTypeRules.*; @SpringBootApplication @EnableSwagger2 @ComponentScan(basePackageClasses = { PetController.class }) public class Swagger2SpringBoot { public static void main(String[] args) { ApplicationContext ctx = SpringApplication.run(Swagger2SpringBoot.class, args); } @Bean public Docket petApi() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.any()) .paths(PathSelectors.any()) .build() .pathMapping("/") .directModelSubstitute(LocalDate.class, String.class) .genericModelSubstitutes(ResponseEntity.class) .alternateTypeRules( newRule(typeResolver.resolve(DeferredResult.class, typeResolver.resolve(ResponseEntity.class, WildcardType.class)), typeResolver.resolve(WildcardType.class))) .useDefaultResponseMessages(false) .globalResponseMessage(RequestMethod.GET, newArrayList(new ResponseMessageBuilder() .code(500) .message("500 message") .responseModel(new ModelRef("Error")) .build())) .securitySchemes(newArrayList(apiKey())) .securityContexts(newArrayList(securityContext())) .enableUrlTemplating(true) .globalOperationParameters( newArrayList(new ParameterBuilder() .name("someGlobalParameter") .description("Description of someGlobalParameter") .modelRef(new ModelRef("string")) .parameterType("query") .required(true) .build())) .tags(new Tag("Pet Service", "All apis relating to pets"))  .additionalModels(typeResolver.resolve(AdditionalModel.class))  ; } @Autowired private TypeResolver typeResolver; private ApiKey apiKey() { return new ApiKey("mykey", "api_key", "header"); } private SecurityContext securityContext() { return SecurityContext.builder() .securityReferences(defaultAuth()) .forPaths(PathSelectors.regex("/anyPath.*")) .build(); } List<SecurityReference> defaultAuth() { AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything"); AuthorizationScope[] authorizationScopes = new AuthorizationScope[1]; authorizationScopes[0] = authorizationScope; return newArrayList( new SecurityReference("mykey", authorizationScopes)); } @Bean SecurityConfiguration security() { return new SecurityConfiguration( "test-app-client-id", "test-app-client-secret", "test-app-realm", "test-app", "apiKey", ApiKeyVehicle.HEADER,  "api_key",  "," /*scope separator*/); } @Bean UiConfiguration uiConfig() { return

weixin_34221036

关注

0
点赞
踩
0

收藏

觉得还不错? 一键收藏
0
评论
Springfox Reference Documentation

1. IntroductionThe Springfox suite of java libraries are all about automating the generation of machine and human readable specifications for JSON APIs written using the spring family of pro...
复制链接

扫一扫